Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

post

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.

Authorizations
AuthorizationstringRequired

Bearer access token. Include in all requests as: Authorization: Bearer <your_access_token>

Header parameters
X-API-KeystringRequired

API key for authentication. Include in all requests.

Example: ehg7q2i6aN8jY6BbHqN5q42KsHQFRwl260jqAkAU
Body

Request to generate a blob for a smart contract invocation.

contractKeystringOptional

Registered contract alias. Either this or contractAddress must be provided.

Example: my-token-contract
contractAddressstringOptional

On-chain contract address. Takes precedence over contractKey if both are given.

Example: ZTX3JK2mN9pQ7rS4tU5vW6xY8zA0bC1dE2fG3hI4
methodstringRequired

Contract method to invoke.

Example: transfer
txInitiatorstring · min: 37 · max: 37Optional

Address of the transaction initiator (pays gas).

Example: ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU
sourceAddressstringOptional

Optional source address override.

valueinteger · int64Optional

ZTX value in drops to send with the invocation. Use 0 for non-payable methods.

Example: 0
Responses
200

Contract invocation blob generated. Sign using /contract/sign-blob then submit via /contract/submit.

*/*
successbooleanOptional
timestampstring · date-timeOptional
traceIdstringOptional
post/ztx/contract/generate-blob
POST /ztx/contract/generate-blob HTTP/1.1
Host: api-sandbox.zetrix.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 203

{
  "contractKey": "my-token-contract",
  "method": "transfer",
  "inputParameters": {
    "to": "ZTX3TkqopBiDmHFMEBr5U7n9HfNqBa7LBhV2Q",
    "amount": "1000000"
  },
  "txInitiator": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU",
  "value": 0
}
200

Contract invocation blob generated. Sign using /contract/sign-blob then submit via /contract/submit.

{
  "success": true,
  "object": {
    "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...",
    "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2",
    "actualFee": 20000
  },
  "messages": [],
  "timestamp": "2026-01-01T10:00:00Z",
  "traceId": "trace-007"
}

Sign contract invocation blob

post

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.

Authorizations
AuthorizationstringRequired

Bearer access token. Include in all requests as: Authorization: Bearer <your_access_token>

Header parameters
X-API-KeystringRequired

API key for authentication. Include in all requests.

Example: ehg7q2i6aN8jY6BbHqN5q42KsHQFRwl260jqAkAU
Body

Request to sign a contract invocation blob using a single private key.

blobstringOptional

Hex-encoded contract invocation blob to sign.

Example: 0A255A5458334A64656A33434B7443724253547851747456666E6456...
privateKeystring · min: 56 · max: 56Optional

56-character Ed25519 private key of the transaction initiator.

Example: privBsRTkj1234567890abcdefghijklmnopqrstuvwxyz12345678
Responses
200

Blob signed. Use the returned listSigner array in /contract/submit.

*/*
successbooleanOptional
timestampstring · date-timeOptional
traceIdstringOptional
post/ztx/contract/sign-blob
POST /ztx/contract/sign-blob HTTP/1.1
Host: api-sandbox.zetrix.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...",
  "privateKey": "privBsRTkj1234567890abcdefghijklmnopqrstuvwxyz12345678"
}
200

Blob signed. Use the returned listSigner array in /contract/submit.

{
  "success": true,
  "object": [
    {
      "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...",
      "publicKey": "b00179b4adb1d3188aa1b98d6977a837..."
    }
  ],
  "messages": [],
  "timestamp": "2026-01-01T10:00:01Z",
  "traceId": "trace-008"
}

Submit signed contract invocation

post

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.

Authorizations
AuthorizationstringRequired

Bearer access token. Include in all requests as: Authorization: Bearer <your_access_token>

Header parameters
X-API-KeystringRequired

API key for authentication. Include in all requests.

Example: ehg7q2i6aN8jY6BbHqN5q42KsHQFRwl260jqAkAU
Body

Request to submit a signed contract invocation blob to the blockchain.

blobstringOptional

Hex-encoded signed blob from /contract/generate-blob.

Example: 0A255A5458334A64656A33434B7443724253547851747456666E6456...
hashstring · min: 64 · max: 64Optional

64-character transaction hash from the generate step.

Example: e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2
initiatorstring · min: 37 · max: 37Optional

37-character Zetrix address of the transaction initiator.

Example: ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU
Responses
200

Contract invocation submitted. Use the returned hash to query the result.

*/*
successbooleanOptional
timestampstring · date-timeOptional
traceIdstringOptional
post/ztx/contract/submit
POST /ztx/contract/submit HTTP/1.1
Host: api-sandbox.zetrix.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 312

{
  "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...",
  "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2",
  "initiator": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU",
  "listSigner": [
    {
      "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...",
      "publicKey": "b00179b4adb1d3188aa1b98d6977a837..."
    }
  ]
}
200

Contract invocation submitted. Use the returned hash to query the result.

{
  "success": true,
  "object": {
    "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2"
  },
  "messages": [],
  "timestamp": "2026-01-01T10:00:02Z",
  "traceId": "trace-009"
}

Query smart contract (read-only)

post

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.

Authorizations
AuthorizationstringRequired

Bearer access token. Include in all requests as: Authorization: Bearer <your_access_token>

Header parameters
X-API-KeystringRequired

API key for authentication. Include in all requests.

Example: ehg7q2i6aN8jY6BbHqN5q42KsHQFRwl260jqAkAU
Body

Request for a read-only smart contract query.

contractKeystringOptional

Registered contract alias in the Zetrix platform.

Example: my-token-contract
methodstringOptional

Read-only contract method to call.

Example: balanceOf
Responses
200

Contract query result. The object field contains the method's return value.

*/*
successbooleanOptional
timestampstring · date-timeOptional
traceIdstringOptional
post/ztx/contract/query
POST /ztx/contract/query HTTP/1.1
Host: api-sandbox.zetrix.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "contractKey": "my-token-contract",
  "method": "balanceOf",
  "inputParameters": {
    "address": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU"
  }
}
200

Contract query result. The object field contains the method's return value.

{
  "success": true,
  "object": {
    "balance": "5000000000"
  },
  "messages": [],
  "timestamp": "2026-01-01T10:00:00Z",
  "traceId": "trace-010"
}

Filter contract call history

get

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
Authorizations
AuthorizationstringRequired

Bearer access token. Include in all requests as: Authorization: Bearer <your_access_token>

Query parameters
contractKeystringOptional

Filter by contract key (registered alias).

Example: my-token-contract
methodstringOptional

Filter by contract method name.

Example: transfer
txInitiatorstringOptional

Filter by transaction initiator address.

Example: ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU
statusstring · enumOptional

Filter by status.

Possible values:
pageintegerOptional

Page number (1-based).

Default: 1
pageSizeintegerOptional

Records per page.

Default: 20
Header parameters
X-API-KeystringRequired

API key for authentication. Include in all requests.

Example: ehg7q2i6aN8jY6BbHqN5q42KsHQFRwl260jqAkAU
Responses
200

Paginated contract history returned.

*/*
successbooleanOptional
timestampstring · date-timeOptional
traceIdstringOptional
get/ztx/contract/history/filter
GET /ztx/contract/history/filter?mapParam=[object+Object] HTTP/1.1
Host: api-sandbox.zetrix.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-API-Key: text
Accept: */*
200

Paginated contract history returned.

{
  "success": true,
  "object": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalElements": 93,
    "content": [
      {
        "id": 1,
        "contractKey": "my-token-contract",
        "address": "ZTX3JK2mN9pQ7rS4tU5vW6xY8zA0bC1dE2fG3hI4",
        "txInitiator": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU",
        "method": "transfer",
        "inputParameters": "{\"to\":\"ZTX3T...\",\"amount\":\"1000000\"}",
        "txHash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2",
        "status": "SUBMITTED",
        "createdAt": "2026-01-01T09:00:00Z",
        "updatedAt": "2026-01-01T09:00:05Z"
      }
    ]
  },
  "messages": [],
  "timestamp": "2026-01-01T10:00:00Z",
  "traceId": "trace-013"
}

Last updated