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

Authorization

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

application/json

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

HTTPcURLJavaScriptPython

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

Authorization

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

application/json

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

HTTPcURLJavaScriptPython

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

Authorization

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

application/json

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

HTTPcURLJavaScriptPython

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

Authorization

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

application/json

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

HTTPcURLJavaScriptPython

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

Authorization

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

HTTPcURLJavaScriptPython

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