> For the complete documentation index, see [llms.txt](https://docs.zetrix.com/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zetrix.com/en/developer-resources/blockchain-as-a-services-baas/zetrix-service/contract.md).

# Contract

Smart contract operations on the Zetrix blockchain. Covers blob generation, signing, submitting, read-only querying, and invocation history filtering for deployed contracts. Includes both standard (user pays gas) and paymaster-sponsored (gas-free) contract invocations.

## Generate contract invocation blob

> Generates a transaction blob for invoking a smart contract method. Either \`contractKey\` (a registered alias) or \`contractAddress\` (on-chain address) must be provided. If both are given, \`contractAddress\` takes precedence.\
> \
> \*\*Flow:\*\*\
> 1\. Call this endpoint with contract identifier, method name, and input parameters\
> 2\. Sign the returned \`blob\` using \`/contract/sign-blob\`\
> 3\. Submit via \`/contract/submit\`\
> \
> \*\*Value:\*\*\
> For payable contract methods, specify \`value\` in drops (1 ZETRIX = 10^6 drops). Use \`0\` for non-payable methods.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"Contract","description":"Smart contract operations on the Zetrix blockchain. Covers blob generation, signing, submitting, read-only querying, and invocation history filtering for deployed contracts. Includes both standard (user pays gas) and paymaster-sponsored (gas-free) contract invocations."}],"servers":[{"url":"https://api-sandbox.zetrix.com","description":"Sandbox Environment – Use this for development and testing."}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer access token. Include in all requests as: `Authorization: Bearer <your_access_token>`"}},"parameters":{"X-API-Key":{"name":"X-API-Key","in":"header","required":true,"description":"API key for authentication. Include in all requests.","schema":{"type":"string"}}},"schemas":{"ContractInvokeGenerateBlobReqDto":{"type":"object","description":"Request to generate a blob for a smart contract invocation.","required":["method"],"properties":{"contractKey":{"type":"string","description":"Registered contract alias. Either this or `contractAddress` must be provided."},"contractAddress":{"type":"string","description":"On-chain contract address. Takes precedence over `contractKey` if both are given."},"method":{"type":"string","description":"Contract method to invoke."},"inputParameters":{"type":"object","additionalProperties":{},"description":"Method input parameters. Structure depends on the contract's ABI."},"txInitiator":{"type":"string","description":"Address of the transaction initiator (pays gas).","minLength":37,"maxLength":37},"sourceAddress":{"type":"string","description":"Optional source address override."},"value":{"type":"integer","format":"int64","description":"ZTX value in drops to send with the invocation. Use `0` for non-payable methods."}}},"ResponseWrapperContractGenerateBlobRespDto":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/ContractGenerateBlobRespDto"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"ContractGenerateBlobRespDto":{"type":"object","description":"Response for contract invocation blob generation.","properties":{"blob":{"type":"string","description":"Hex-encoded contract invocation blob."},"hash":{"type":"string","description":"Transaction hash."},"actualFee":{"type":"integer","format":"int64","description":"Estimated fee in gas units."},"platformSignData":{"$ref":"#/components/schemas/PlatformSignDataEntity"}}},"PlatformSignDataEntity":{"type":"object","description":"Optional platform co-signature data, present when the platform pre-signs the blob.","properties":{"publicKey":{"type":"string","description":"Platform's public key."},"signBlob":{"type":"string","description":"Platform's signature of the blob."}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}},"paths":{"/ztx/contract/generate-blob":{"post":{"tags":["Contract"],"summary":"Generate contract invocation blob","operationId":"invokeGenerateBlobByKey","parameters":[{"$ref":"#/components/parameters/X-API-Key"}],"description":"Generates a transaction blob for invoking a smart contract method. Either `contractKey` (a registered alias) or `contractAddress` (on-chain address) must be provided. If both are given, `contractAddress` takes precedence.\n\n**Flow:**\n1. Call this endpoint with contract identifier, method name, and input parameters\n2. Sign the returned `blob` using `/contract/sign-blob`\n3. Submit via `/contract/submit`\n\n**Value:**\nFor payable contract methods, specify `value` in drops (1 ZETRIX = 10^6 drops). Use `0` for non-payable methods.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractInvokeGenerateBlobReqDto"}}}},"responses":{"200":{"description":"Contract invocation blob generated. Sign using `/contract/sign-blob` then submit via `/contract/submit`.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperContractGenerateBlobRespDto"}}}}}}}}}
```

## Sign contract invocation blob

> Signs a contract invocation blob using a single private key. Server-side Ed25519 signing convenience endpoint.\
> \
> \*\*Input:\*\*\
> \- \`blob\` — The hex-encoded blob from \`/contract/generate-blob\`\
> \- \`privateKey\` — A 56-character Ed25519 private key\
> \
> \*\*Output:\*\*\
> A \`SignerEntity\` list with \`signBlob\` (signature) and \`publicKey\`. Pass as \`listSigner\` to \`/contract/submit\`.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"Contract","description":"Smart contract operations on the Zetrix blockchain. Covers blob generation, signing, submitting, read-only querying, and invocation history filtering for deployed contracts. Includes both standard (user pays gas) and paymaster-sponsored (gas-free) contract invocations."}],"servers":[{"url":"https://api-sandbox.zetrix.com","description":"Sandbox Environment – Use this for development and testing."}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer access token. Include in all requests as: `Authorization: Bearer <your_access_token>`"}},"parameters":{"X-API-Key":{"name":"X-API-Key","in":"header","required":true,"description":"API key for authentication. Include in all requests.","schema":{"type":"string"}}},"schemas":{"ContractInvokeSignBlobReqDto":{"type":"object","description":"Request to sign a contract invocation blob using a single private key.","properties":{"blob":{"type":"string","description":"Hex-encoded contract invocation blob to sign."},"privateKey":{"type":"string","description":"56-character Ed25519 private key of the transaction initiator.","minLength":56,"maxLength":56}}},"ResponseWrapperListSignerEntity":{"type":"object","properties":{"object":{"type":"array","items":{"$ref":"#/components/schemas/SignerEntity"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"SignerEntity":{"type":"object","description":"A signer object containing a signature and public key pair. Used in transaction/contract submission requests.","properties":{"signBlob":{"type":"string","description":"Hex-encoded Ed25519 signature of the transaction blob."},"publicKey":{"type":"string","description":"Hex-encoded Ed25519 public key of the signer. Must be exactly 76 characters.","minLength":76,"maxLength":76}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}},"paths":{"/ztx/contract/sign-blob":{"post":{"tags":["Contract"],"summary":"Sign contract invocation blob","operationId":"invokeSignBlob","parameters":[{"$ref":"#/components/parameters/X-API-Key"}],"description":"Signs a contract invocation blob using a single private key. Server-side Ed25519 signing convenience endpoint.\n\n**Input:**\n- `blob` — The hex-encoded blob from `/contract/generate-blob`\n- `privateKey` — A 56-character Ed25519 private key\n\n**Output:**\nA `SignerEntity` list with `signBlob` (signature) and `publicKey`. Pass as `listSigner` to `/contract/submit`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractInvokeSignBlobReqDto"}}}},"responses":{"200":{"description":"Blob signed. Use the returned `listSigner` array in `/contract/submit`.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperListSignerEntity"}}}}}}}}}
```

## Submit signed contract invocation

> Submits a signed contract invocation blob to the Zetrix blockchain. Final step in the standard contract invocation flow.\
> \
> \*\*Pre-conditions:\*\*\
> \- \`blob\` from \`/contract/generate-blob\`\
> \- \`listSigner\` from \`/contract/sign-blob\` or your own signer\
> \- \`hash\` — 64-character transaction hash from the generate step\
> \- \`initiator\` — 37-character address of the transaction initiator\
> \
> \*\*After Submission:\*\*\
> Use the returned \`hash\` with \`/tx/query\` to confirm on-chain status.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"Contract","description":"Smart contract operations on the Zetrix blockchain. Covers blob generation, signing, submitting, read-only querying, and invocation history filtering for deployed contracts. Includes both standard (user pays gas) and paymaster-sponsored (gas-free) contract invocations."}],"servers":[{"url":"https://api-sandbox.zetrix.com","description":"Sandbox Environment – Use this for development and testing."}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer access token. Include in all requests as: `Authorization: Bearer <your_access_token>`"}},"parameters":{"X-API-Key":{"name":"X-API-Key","in":"header","required":true,"description":"API key for authentication. Include in all requests.","schema":{"type":"string"}}},"schemas":{"ContractInvokeSubmitReqDto":{"type":"object","description":"Request to submit a signed contract invocation blob to the blockchain.","properties":{"blob":{"type":"string","description":"Hex-encoded signed blob from `/contract/generate-blob`."},"hash":{"type":"string","description":"64-character transaction hash from the generate step.","minLength":64,"maxLength":64},"initiator":{"type":"string","description":"37-character Zetrix address of the transaction initiator.","minLength":37,"maxLength":37},"listSigner":{"type":"array","description":"Signers with their signatures and public keys.","items":{"$ref":"#/components/schemas/SignerEntity"}}}},"SignerEntity":{"type":"object","description":"A signer object containing a signature and public key pair. Used in transaction/contract submission requests.","properties":{"signBlob":{"type":"string","description":"Hex-encoded Ed25519 signature of the transaction blob."},"publicKey":{"type":"string","description":"Hex-encoded Ed25519 public key of the signer. Must be exactly 76 characters.","minLength":76,"maxLength":76}}},"ResponseWrapperContractSubmitRespDto":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/ContractSubmitRespDto"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"ContractSubmitRespDto":{"type":"object","properties":{"hash":{"type":"string","description":"Transaction hash confirming contract invocation was broadcast."}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}},"paths":{"/ztx/contract/submit":{"post":{"tags":["Contract"],"summary":"Submit signed contract invocation","operationId":"invokeSubmit","parameters":[{"$ref":"#/components/parameters/X-API-Key"}],"description":"Submits a signed contract invocation blob to the Zetrix blockchain. Final step in the standard contract invocation flow.\n\n**Pre-conditions:**\n- `blob` from `/contract/generate-blob`\n- `listSigner` from `/contract/sign-blob` or your own signer\n- `hash` — 64-character transaction hash from the generate step\n- `initiator` — 37-character address of the transaction initiator\n\n**After Submission:**\nUse the returned `hash` with `/tx/query` to confirm on-chain status.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractInvokeSubmitReqDto"}}}},"responses":{"200":{"description":"Contract invocation submitted. Use the returned `hash` to query the result.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperContractSubmitRespDto"}}}}}}}}}
```

## Query smart contract (read-only)

> Performs a \*\*read-only\*\* query against a deployed smart contract. No transaction is created, no gas is consumed, and no state change occurs.\
> \
> \*\*Use Cases:\*\*\
> \- Check token balances\
> \- Read contract configuration\
> \- Verify ownership or access rights\
> \- Fetch metadata stored in the contract\
> \
> \*\*Response:\*\*\
> The \`object\` field contains the raw JSON returned by the contract method. Its structure varies per contract and method.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"Contract","description":"Smart contract operations on the Zetrix blockchain. Covers blob generation, signing, submitting, read-only querying, and invocation history filtering for deployed contracts. Includes both standard (user pays gas) and paymaster-sponsored (gas-free) contract invocations."}],"servers":[{"url":"https://api-sandbox.zetrix.com","description":"Sandbox Environment – Use this for development and testing."}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer access token. Include in all requests as: `Authorization: Bearer <your_access_token>`"}},"parameters":{"X-API-Key":{"name":"X-API-Key","in":"header","required":true,"description":"API key for authentication. Include in all requests.","schema":{"type":"string"}}},"schemas":{"ContractQueryReqDto":{"type":"object","description":"Request for a read-only smart contract query.","properties":{"contractKey":{"type":"string","description":"Registered contract alias in the Zetrix platform."},"method":{"type":"string","description":"Read-only contract method to call."},"inputParameters":{"type":"object","additionalProperties":{},"description":"Input parameters for the method. Structure depends on the contract's ABI."}}},"ResponseWrapperJSONObject":{"type":"object","properties":{"object":{"type":"object","additionalProperties":{},"description":"Dynamic JSON response from the smart contract method."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}},"paths":{"/ztx/contract/query":{"post":{"tags":["Contract"],"summary":"Query smart contract (read-only)","operationId":"query","parameters":[{"$ref":"#/components/parameters/X-API-Key"}],"description":"Performs a **read-only** query against a deployed smart contract. No transaction is created, no gas is consumed, and no state change occurs.\n\n**Use Cases:**\n- Check token balances\n- Read contract configuration\n- Verify ownership or access rights\n- Fetch metadata stored in the contract\n\n**Response:**\nThe `object` field contains the raw JSON returned by the contract method. Its structure varies per contract and method.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractQueryReqDto"}}}},"responses":{"200":{"description":"Contract query result. The `object` field contains the method's return value.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperJSONObject"}}}}}}}}}
```

## Filter contract call history

> Retrieves a paginated history of smart contract invocations, filtered by query parameters.\
> \
> \*\*Supported Filter Parameters:\*\*\
> \- \`contractKey\` — Filter by contract alias\
> \- \`method\` — Filter by contract method name\
> \- \`txInitiator\` — Filter by initiator address\
> \- \`status\` — \`INITIATED\` or \`SUBMITTED\`\
> \- \`page\` — Page number (1-based)\
> \- \`pageSize\` — Records per page\
> \
> \*\*Example:\*\*\
> \`\`\`\
> GET /contract/history/filter?contractKey=my-token-contract\&method=transfer\&page=1\&pageSize=20\
> \`\`\`

````json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"Contract","description":"Smart contract operations on the Zetrix blockchain. Covers blob generation, signing, submitting, read-only querying, and invocation history filtering for deployed contracts. Includes both standard (user pays gas) and paymaster-sponsored (gas-free) contract invocations."}],"servers":[{"url":"https://api-sandbox.zetrix.com","description":"Sandbox Environment – Use this for development and testing."}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer access token. Include in all requests as: `Authorization: Bearer <your_access_token>`"}},"parameters":{"X-API-Key":{"name":"X-API-Key","in":"header","required":true,"description":"API key for authentication. Include in all requests.","schema":{"type":"string"}}},"schemas":{"MultiValueMapStringString":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Multi-value map for flexible filter parameters."},"ResponseWrapperResponsePaginatedContractUsageHistoryRespDto":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/ResponsePaginatedContractUsageHistoryRespDto"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"ResponsePaginatedContractUsageHistoryRespDto":{"type":"object","properties":{"page":{"type":"integer","format":"int64"},"pageSize":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"content":{"type":"array","items":{"$ref":"#/components/schemas/ContractUsageHistoryRespDto"}}}},"ContractUsageHistoryRespDto":{"type":"object","description":"A single contract invocation history record.","properties":{"id":{"type":"integer","format":"int64","description":"Internal record ID."},"address":{"type":"string","description":"Contract on-chain address."},"contractKey":{"type":"string","description":"Contract alias key."},"txInitiator":{"type":"string","description":"Address that initiated the transaction."},"method":{"type":"string","description":"Contract method called."},"inputParameters":{"type":"string","description":"JSON-serialized input parameters."},"txHash":{"type":"string","description":"Transaction hash."},"status":{"type":"string","enum":["INITIATED","SUBMITTED"],"description":"Invocation status."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}},"paths":{"/ztx/contract/history/filter":{"get":{"tags":["Contract"],"summary":"Filter contract call history","operationId":"filterHistory","description":"Retrieves a paginated history of smart contract invocations, filtered by query parameters.\n\n**Supported Filter Parameters:**\n- `contractKey` — Filter by contract alias\n- `method` — Filter by contract method name\n- `txInitiator` — Filter by initiator address\n- `status` — `INITIATED` or `SUBMITTED`\n- `page` — Page number (1-based)\n- `pageSize` — Records per page\n\n**Example:**\n```\nGET /contract/history/filter?contractKey=my-token-contract&method=transfer&page=1&pageSize=20\n```","parameters":[{"$ref":"#/components/parameters/X-API-Key"},{"name":"contractKey","in":"query","required":false,"description":"Filter by contract key (registered alias).","schema":{"type":"string"}},{"name":"method","in":"query","required":false,"description":"Filter by contract method name.","schema":{"type":"string"}},{"name":"txInitiator","in":"query","required":false,"description":"Filter by transaction initiator address.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status.","schema":{"type":"string","enum":["INITIATED","SUBMITTED"]}},{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","required":false,"description":"Records per page.","schema":{"type":"integer","default":20}},{"name":"mapParam","in":"query","required":true,"description":"Multi-value map combining all filter parameters above.","schema":{"$ref":"#/components/schemas/MultiValueMapStringString"}}],"responses":{"200":{"description":"Paginated contract history returned.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperResponsePaginatedContractUsageHistoryRespDto"}}}}}}}}}
````