# 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"}}}}}}}}}
````


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zetrix.com/en/developer-resources/blockchain-as-a-services-baas/zetrix-service/contract.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.