{ "openapi": "3.1.0", "info": { "title": "Zetrix Microservice API", "description": "The Zetrix Blockchain-as-a-Service (BaaS) API enables developers to interact with the Zetrix blockchain network programmatically.\n\nCapabilities include:\n- Standard transactions (user pays gas)\n- Paymaster transactions (gas-free, platform sponsors gas)\n- Smart contract invocation and querying\n- Contract call history retrieval\n- Core blockchain network monitoring", "version": "1.0.0", "contact": { "name": "", "email": "" } }, "servers": [ { "url": "https://api-sandbox.zetrix.com", "description": "Sandbox Environment – Use this for development and testing." } ], "security": [ { "Authorization": [] } ], "tags": [ { "name": "Core", "description": "Blockchain network monitoring endpoints. Retrieve block height, blockchain statistics, node lists, node counts by geography, total ZTX supply, and circulating supply." }, { "name": "Transaction", "description": "Full transaction lifecycle operations on the Zetrix blockchain. Covers generating, signing, parsing, submitting, and querying both **standard transactions** (user pays gas) and **paymaster-sponsored transactions** (gas-free for users). Typical standard flow: generate blob → sign blob → submit → query." }, { "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." }, { "name": "Paymaster", "description": "Gas-free transaction and contract invocation operations where the **Paymaster service sponsors the gas fee** on behalf of the user. Ideal for onboarding new users who don't hold ZTX tokens. Flow: generate paymaster blob → sign blob → submit paymaster." }, { "name": "HSM", "description": "Hardware Security Module — Thales Luna Cloud (DPoD)" } ], "paths": { "/ztx/core/block-height": { "get": { "tags": ["Core"], "summary": "Get current block height", "operationId": "getBlockHeight", "description": "Returns the current (latest) block height of the Zetrix blockchain. The block height is a sequential integer representing the most recently confirmed block.\n\n**Use Cases:**\n- Verify the network is active and progressing\n- Use as a reference point for auditing transaction timing\n- Monitor chain health during integration testing", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "responses": { "200": { "description": "Current block height.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperLong" }, "example": { "success": true, "object": 8472910, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-015" } } } } } } }, "/ztx/core/blockchain-info": { "get": { "tags": ["Core"], "summary": "Get blockchain overview", "operationId": "getBlockchainInfo", "description": "Returns a comprehensive snapshot of the Zetrix blockchain's current state, including transaction counts, account counts, TPS metrics, average block generation time, and the latest ledgers and transactions.\n\n**Returned Metrics:**\n- `blockchainHeight` — Current block height\n- `transactionNum` — Total transactions on-chain\n- `accountNum` — Total accounts created\n- `txTpsMax` / `currentTps` — Maximum and current transactions per second\n- `blockAverageGeneTime` — Average block generation time in milliseconds\n- `netStatus` — Network health status (`NORMAL`, `DEGRADED`)\n- `lastLedgerList` — Most recent blocks\n- `lastTxList` — Most recent transactions", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "responses": { "200": { "description": "Blockchain overview and statistics.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperDSMonitoringBlockchain" }, "example": { "success": true, "object": { "chainId": 1, "blockchainHeight": 8472910, "transactionNum": 1500000, "accountNum": 50000, "txTpsMax": 1000, "currentTps": 12, "blockAverageGeneTime": 3000, "netStatus": "NORMAL", "chainName": "Zetrix Mainnet" }, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-016" } } } } } } }, "/ztx/core/node-stat": { "get": { "tags": ["Core"], "summary": "Get node statistics", "operationId": "getNodeStat", "description": "Returns aggregated statistics for all validator and synchronous nodes on the Zetrix network.\n\n**Returned Data:**\n- `total` — Total number of nodes\n- `validatorNodeStat` — Online/offline/warning counts for validator nodes\n- `synchronousNodeStat` — Online/offline/warning counts for sync nodes\n\n**Use Cases:**\n- Monitor network health and node availability\n- Alert on high offline or warning node counts", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "responses": { "200": { "description": "Node statistics for validator and synchronous nodes.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperDSMonitoringNodeStatWrapper" }, "example": { "success": true, "object": { "total": 30, "validatorNodeStat": { "total": 20, "onlineCount": 18, "offlineCount": 1, "warnCount": 1 }, "synchronousNodeStat": { "total": 10, "onlineCount": 10, "offlineCount": 0, "warnCount": 0 } }, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-017" } } } } } } }, "/ztx/core/node-list": { "get": { "tags": ["Core"], "summary": "Get paginated node list", "operationId": "getNodeList", "description": "Returns a paginated list of blockchain nodes, filterable by node type. Each entry includes address, status, type, OS, block sync state, and certificate/license expiry.\n\n**Parameters:**\n- `nodeType` — Filter by type: `VALIDATOR` or `SYNCHRONOUS`\n- `pageNo` — Page number (1-based)\n- `pageSize` — Records per page", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" }, { "name": "nodeType", "in": "query", "required": true, "description": "Type of node to list. Accepted values: `VALIDATOR`, `SYNCHRONOUS`.", "schema": { "type": "string" }, "example": "VALIDATOR" }, { "name": "pageNo", "in": "query", "required": true, "description": "Page number (1-based).", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "pageSize", "in": "query", "required": true, "description": "Number of records per page.", "schema": { "type": "integer", "format": "int32" }, "example": 10 } ], "responses": { "200": { "description": "Paginated node list.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperDSMonitoringPagination" }, "example": { "success": true, "object": { "pageNum": 1, "pageSize": 10, "total": 20, "content": [ { "nodeName": "validator-node-01", "nodeAddress": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU", "nodeType": "VALIDATOR", "nodeStatus": "ONLINE", "blockSeq": "8472910" } ] }, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-018" } } } } } } }, "/ztx/core/node-count": { "get": { "tags": ["Core"], "summary": "Get node count by geography", "operationId": "getNodeInfo", "description": "Returns the count of blockchain nodes grouped by geography code. Useful for visualizing the geographic distribution of the Zetrix network.\n\n**Response:**\nA list of objects, each with a `geographyCode` (numeric ISO region identifier) and a `total` node count for that region.", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "responses": { "200": { "description": "Node counts grouped by geography code.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperListDSMonitoringNode" }, "example": { "success": true, "object": [ { "geographyCode": 458, "total": 12 }, { "geographyCode": 840, "total": 5 }, { "geographyCode": 156, "total": 3 } ], "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-019" } } } } } } }, "/ztx/core/total-supply": { "get": { "tags": ["Core"], "summary": "Get total ZTX supply", "operationId": "getTotalSupply", "description": "Returns the total supply of ZTX tokens ever created on the Zetrix blockchain — the maximum possible supply including all tokens in circulation, locked, or staked.\n\n**Note:** Returns a string to preserve precision for large integer values.", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "responses": { "200": { "description": "Total ZTX token supply as a string.", "content": { "*/*": { "schema": { "type": "string" }, "example": "10000000000000000" } } } } } }, "/ztx/core/circulation-supply": { "get": { "tags": ["Core"], "summary": "Get circulating ZTX supply", "operationId": "getCirculationSupply", "description": "Returns the current circulating supply of ZTX tokens — the amount actively in circulation, excluding locked, burned, or reserved tokens.\n\n**Note:** Returns a string to preserve precision for large integer values.", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "responses": { "200": { "description": "Current circulating ZTX supply as a string.", "content": { "*/*": { "schema": { "type": "string" }, "example": "7500000000000000" } } } } } }, "/ztx/tx/generate-blob": { "post": { "tags": ["Transaction"], "summary": "Generate transaction blob", "operationId": "generateBlob", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "description": "Generates a serialized transaction blob for a standard transaction where the **user pays gas fees**.\n\n**Flow:**\n1. Call this endpoint with `txInitiator` (the address paying gas) and `operations`\n2. Receive `blob` and `hash`\n3. Sign using `/tx/sign-blob` or your own Ed25519 signer\n4. Submit via `/tx/submit`\n\n**Operations:**\nThe `operations` array defines what the transaction does. Supported types include `SEND_GAS`, `TRANSFER`, `CONTRACT_INVOKE`, and more.\n\n**Note:** For gas-free transactions, use `/tx/paymaster/generate-blob` instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateBlobReqDto" }, "example": { "txInitiator": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU", "chainCode": "0", "operations": [ { "type": "SEND_GAS", "toAddress": "ZTX3TkqopBiDmHFMEBr5U7n9HfNqBa7LBhV2Q", "amount": "1000000" } ] } } } }, "responses": { "200": { "description": "Transaction blob generated successfully. Sign the `blob` and submit via `/tx/submit`.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperGenerateBlobRespDto" }, "example": { "success": true, "object": { "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2", "actualFee": 15000 }, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-001" } } } } } } }, "/ztx/tx/sign-blob": { "post": { "tags": ["Transaction"], "summary": "Sign transaction blob", "operationId": "signBlob", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "description": "Signs a transaction blob using one or more private keys. A convenience helper for Ed25519 signing on the server side.\n\n**Output:**\nReturns a `listSigner` array — one entry per key — each containing `signBlob` (signature) and `publicKey`. Pass this directly to `/tx/submit` or `/contract/submit`.\n\n**Security Note:**\nYou are transmitting private keys over the network. Ensure HTTPS is used. For higher-security environments, consider client-side signing instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlobDataReqDto" }, "example": { "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2", "privateKeys": ["privBsRTkj1234567890abcdefghijklmnopqrstuvwxyz12345678"] } } } }, "responses": { "200": { "description": "Blob signed. Use the returned `listSigner` in `/tx/submit` or `/contract/submit`.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperListSignerEntity" }, "example": { "success": true, "object": [ { "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...", "publicKey": "b00179b4adb1d3188aa1b98d6977a837..." } ], "messages": [], "timestamp": "2026-01-01T10:00:01Z", "traceId": "trace-002" } } } } } } }, "/ztx/tx/submit": { "post": { "tags": ["Transaction"], "summary": "Submit transaction", "operationId": "submit", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "description": "Submits a **signed transaction blob** synchronously to the Zetrix blockchain where the user pays gas fees. Blocks until the transaction is confirmed or rejected.\n\n**Pre-conditions:**\n- `blob` from `/tx/generate-blob`\n- `listSigner` from `/tx/sign-blob` or your own signer\n\n**After submission:**\nUse the returned `hash` to track via `/tx/query`.\n\n**Note:** For gas-free submission, use `/tx/paymaster/submit` instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitTxReqDto" }, "example": { "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "listSigner": [ { "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...", "publicKey": "b00179b4adb1d3188aa1b98d6977a837..." } ] } } } }, "responses": { "200": { "description": "Transaction submitted and confirmed. Use `hash` to query status.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperTxSubmitRespDto" }, "example": { "success": true, "object": { "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2" }, "messages": [], "timestamp": "2026-01-01T10:00:02Z", "traceId": "trace-003" } } } } } } }, "/ztx/tx/parse-blob": { "post": { "tags": ["Transaction"], "summary": "Parse transaction blob", "operationId": "parseBlob", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "description": "Decodes a hex-encoded transaction blob and returns its human-readable contents: source address, operations, nonce, gas parameters, and chain ID.\n\n**Use Cases:**\n- Verify what operations are encoded before signing\n- Debug or audit transaction contents\n- Display transaction details to users for confirmation\n\n**Note:** Read-only — does not interact with the blockchain.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseBlobReqDto" }, "example": { "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456..." } } } }, "responses": { "200": { "description": "Blob parsed. Returns decoded transaction details.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperTransactionParseBlobResult" }, "example": { "success": true, "object": { "sourceAddress": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU", "feeLimit": 50000, "gasPrice": 1000, "nonce": 42, "chainId": 1, "operations": [ { "type": "SEND_GAS", "sendGas": { "destAddress": "ZTX3TkqopBiDmHFMEBr5U7n9HfNqBa7LBhV2Q", "amount": 1000000 } } ] }, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-004" } } } } } } }, "/ztx/tx/query": { "get": { "tags": ["Transaction"], "summary": "Query transaction by hash", "operationId": "queryTransaction", "description": "Retrieves the status and full details of a submitted transaction using its transaction hash.\n\nFor `txStatus` lifecycle codes and `errorCode` definitions, refer to the [Zetrix WebSocket Error Codes](https://docs.zetrix.com/en/developer-resources/api/websocket#error-codes).\n\n**Note:** For paymaster transactions, allow a few seconds after submission before querying as processing is asynchronous.", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" }, { "name": "hash", "in": "query", "required": true, "description": "The 64-character transaction hash to look up.", "schema": { "type": "string", "minLength": 64, "maxLength": 64 }, "example": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2" } ], "responses": { "200": { "description": "Transaction details returned.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperTxQueryRespDto" }, "example": { "object": { "txStatus": "0", "txContent": { "actualFee": "4090", "closeTime": 1778040148964508, "contractTxHashes": null, "errorCode": 0, "errorDesc": "", "hash": "cf669ed4bf659635b44090d7c4abe3eded43f21f16f19f7214a3ec4624b26833", "ledgerSeq": 3861063, "signatures": [ { "signData": "894f05e243e3c6458d422da208ecbe6be863335854c47edffcab1456be7c9eb696fe871d06a7311aad058d134aad62632e89fcc4c7bf326e970825c07415b302", "publicKey": "b00148d7a3e15b4b21b28dfd315a6b4dbdb8bf068cef7f2fc2bb73cd173911d8f9cf93d6ec17" }, { "signData": "20ffa0a2e42413cf40a828b5ac1df1c32836fac4ae9ceb359c0ffc540eb682640d6f5110445870abb90ed8aa909ef6f5c9b7c0d1d840d5eda6f5cdad0ecbe307", "publicKey": "b001f2da4b0f94b7e4086850e4b83a144912eeb4af71c9c81d3e6617610b5b084dcb0f129a76" } ], "transaction": { "sourceAddress": "ZTX3PUg6GzYWQKUKJLSnwzztyxFwAhvuYVEmG", "feeLimit": 1000000, "gasPrice": 10, "nonce": 1581, "metadata": null, "operations": [ { "type": 7, "sourceAddress": null, "metadata": null, "createAccount": null, "issueAsset": null, "sendAsset": null, "sendGas": { "destAddress": "ZTX3GpYLUSFjdwJwjggScktuuDQCkUgo1tCKn", "amount": 1000000, "input": null }, "setMetadata": null, "setPrivilege": null, "upgradeContract": null, "log": null } ], "chainId": null }, "trigger": null, "txSize": 409 } }, "messages": [], "success": true, "timestamp": "2026-05-06 12:11:52", "traceId": "4b6a01c5-8d09-4d71-80ff-0198ee112baf" } } } } } } }, "/ztx/tx/paymaster/generate-blob": { "post": { "tags": ["Paymaster"], "summary": "Generate paymaster transaction blob", "operationId": "generatePaymasterBlob", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "description": "Generates a gas-free transaction blob using the Zetrix Paymaster service. The Paymaster allocates a nonce from its pool and sponsors the gas fee when the transaction is submitted.\n\n**Flow:**\n1. Call this endpoint with `userAddress` and `operations`\n2. Receive `blob`, `blobId`, and reservation expiry (`expiresAt`)\n3. Sign the blob using `/tx/sign-blob`\n4. Submit via `/tx/paymaster/submit` within `timeoutMinutes`\n\n**Pool Selection:**\nAuto-selected unless `paymasterPoolId` or `poolType` (`NORMAL`, `PREMIUM`, `CORPORATE`) is specified.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymasterGenerateBlobReqDto" }, "example": { "userAddress": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU", "operations": [ { "type": "SEND_GAS", "toAddress": "ZTX3TkqopBiDmHFMEBr5U7n9HfNqBa7LBhV2Q", "amount": "1000000" } ], "chainCode": "0", "timeoutMinutes": 10, "poolType": "NORMAL", "metadata": { "appId": "mobile-app", "version": "1.0.0" } } } } }, "responses": { "200": { "description": "Paymaster blob generated. Sign and submit via `/tx/paymaster/submit` before `expiresAt`.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperPaymasterGenerateBlobRespDto" }, "example": { "success": true, "object": { "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2", "blobId": "550e8400-e29b-41d4-a716-446655440000", "paymasterAddress": "ZTX9876543210ZYXWVUTSRQPONMLKJIHGFED", "paymasterNonce": 42, "paymasterPoolId": 1, "actualFee": 15000, "expiresAt": "2026-01-01T10:10:00Z", "timeoutMinutes": 10 }, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-005" } } } } } } }, "/ztx/tx/paymaster/submit": { "post": { "tags": ["Paymaster"], "summary": "Submit paymaster transaction", "operationId": "submitPaymasterTransaction", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "description": "Submits a signed paymaster transaction blob for asynchronous processing. Returns immediately with `QUEUED` status.\n\n**Pre-conditions:**\n- `blobId` from a valid, non-expired `/tx/paymaster/generate-blob` call\n- `blob` signed by the user's private key\n- Submitted before `expiresAt`\n\n**Async Processing:**\nThe Paymaster adds its gas-sponsoring signature and broadcasts the transaction. Poll `/tx/query` with `txHash` to check final status.\n\n**Response Fields:**\n- `status` — Initially `QUEUED`\n- `txHash` — Use this to query the final result", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymasterSubmitReqDto" }, "example": { "blobId": "550e8400-e29b-41d4-a716-446655440000", "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "listSigner": [ { "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...", "publicKey": "b00179b4adb1d3188aa1b98d6977a837..." } ] } } } }, "responses": { "200": { "description": "Transaction queued for paymaster processing. Poll `/tx/query` using `txHash` for final status.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperPaymasterSubmitRespDto" }, "example": { "success": true, "object": { "txHash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2", "blobId": "550e8400-e29b-41d4-a716-446655440000", "status": "QUEUED", "paymasterAddress": "ZTX9876543210ZYXWVUTSRQPONMLKJIHGFED", "nonce": 42, "submittedAt": "2026-01-01T10:01:00Z" }, "messages": [], "timestamp": "2026-01-01T10:01:00Z", "traceId": "trace-006" } } } } } } }, "/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" }, "example": { "contractKey": "my-token-contract", "method": "transfer", "inputParameters": { "to": "ZTX3TkqopBiDmHFMEBr5U7n9HfNqBa7LBhV2Q", "amount": "1000000" }, "txInitiator": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU", "value": 0 } } } }, "responses": { "200": { "description": "Contract invocation blob generated. Sign using `/contract/sign-blob` then submit via `/contract/submit`.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperContractGenerateBlobRespDto" }, "example": { "success": true, "object": { "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2", "actualFee": 20000 }, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-007" } } } } } } }, "/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" }, "example": { "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "privateKey": "privBsRTkj1234567890abcdefghijklmnopqrstuvwxyz12345678" } } } }, "responses": { "200": { "description": "Blob signed. Use the returned `listSigner` array in `/contract/submit`.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperListSignerEntity" }, "example": { "success": true, "object": [ { "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...", "publicKey": "b00179b4adb1d3188aa1b98d6977a837..." } ], "messages": [], "timestamp": "2026-01-01T10:00:01Z", "traceId": "trace-008" } } } } } } }, "/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" }, "example": { "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2", "initiator": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU", "listSigner": [ { "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...", "publicKey": "b00179b4adb1d3188aa1b98d6977a837..." } ] } } } }, "responses": { "200": { "description": "Contract invocation submitted. Use the returned `hash` to query the result.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperContractSubmitRespDto" }, "example": { "success": true, "object": { "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2" }, "messages": [], "timestamp": "2026-01-01T10:00:02Z", "traceId": "trace-009" } } } } } } }, "/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" }, "example": { "contractKey": "my-token-contract", "method": "balanceOf", "inputParameters": { "address": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU" } } } } }, "responses": { "200": { "description": "Contract query result. The `object` field contains the method's return value.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperJSONObject" }, "example": { "success": true, "object": { "balance": "5000000000" }, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-010" } } } } } } }, "/ztx/contract/paymaster/generate-blob": { "post": { "tags": ["Paymaster"], "summary": "Generate paymaster contract invocation blob", "operationId": "generatePaymasterBlob_1", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "description": "Generates a gas-free contract invocation blob using the Paymaster service. Either `contractKey` or `contractAddress` must be provided. If both are given, `contractAddress` takes precedence.\n\n**Flow:**\n1. Call this endpoint with the user's address, contract identifier, method, and input parameters\n2. Receive `blob`, `blobId`, and expiry info\n3. Sign the blob using `/tx/sign-blob`\n4. Submit via `/contract/paymaster/submit` before `expiresAt`\n\n**Pool Selection:**\nAuto-selected unless `paymasterPoolId` or `poolType` (`NORMAL`, `PREMIUM`, `CORPORATE`) is specified.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractPaymasterGenerateBlobReqDto" }, "example": { "contractKey": "my-token-contract", "method": "transfer", "inputParameters": { "to": "ZTX3TkqopBiDmHFMEBr5U7n9HfNqBa7LBhV2Q", "amount": "1000000" }, "userAddress": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU", "value": 0, "chainCode": "0", "timeoutMinutes": 10, "poolType": "NORMAL", "metadata": { "appId": "mobile-app", "version": "1.0.0" } } } } }, "responses": { "200": { "description": "Paymaster contract blob generated. Sign and submit via `/contract/paymaster/submit` before expiry.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperContractPaymasterGenerateBlobRespDto" }, "example": { "success": true, "object": { "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "hash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2", "blobId": "550e8400-e29b-41d4-a716-446655440000", "paymasterAddress": "ZTX9876543210ZYXWVUTSRQPONMLKJIHGFED", "paymasterNonce": 42, "paymasterPoolId": 1, "contractAddress": "ZTX3JK2mN9pQ7rS4tU5vW6xY8zA0bC1dE2fG3hI4", "method": "transfer", "actualFee": 20000, "expiresAt": "2026-01-01T10:10:00Z", "timeoutMinutes": 10 }, "messages": [], "timestamp": "2026-01-01T10:00:00Z", "traceId": "trace-011" } } } } } } }, "/ztx/contract/paymaster/submit": { "post": { "tags": ["Paymaster"], "summary": "Submit paymaster contract invocation", "operationId": "submitPaymasterTransaction_1", "parameters": [ { "$ref": "#/components/parameters/X-API-Key" } ], "description": "Queues a signed contract invocation blob for asynchronous Paymaster processing. Returns immediately with `QUEUED` status. The Paymaster adds its gas-sponsoring signature and broadcasts the transaction.\n\n**Required fields:**\n- `blobId` — from `/contract/paymaster/generate-blob`\n- `blob` — signed by the user\n- `listSigner` — user's signature(s)\n\n**Tracking:**\nPoll `/tx/query` with `txHash` to check final on-chain status.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymasterSubmitReqDto" }, "example": { "blobId": "550e8400-e29b-41d4-a716-446655440000", "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...", "listSigner": [ { "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...", "publicKey": "b00179b4adb1d3188aa1b98d6977a837..." } ] } } } }, "responses": { "200": { "description": "Contract invocation queued for paymaster processing.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperPaymasterSubmitRespDto" }, "example": { "success": true, "object": { "txHash": "e3ea722dfaf33ca7a970348f55be0ba51abedfbd15e840ffb63fd9d7202b7eb2", "blobId": "550e8400-e29b-41d4-a716-446655440000", "status": "QUEUED", "paymasterAddress": "ZTX9876543210ZYXWVUTSRQPONMLKJIHGFED", "nonce": 42, "submittedAt": "2026-01-01T10:01:00Z" }, "messages": [], "timestamp": "2026-01-01T10:01:00Z", "traceId": "trace-012" } } } } } } }, "/ztx/hsm/create-account": { "post": { "tags": ["HSM"], "summary": "Create HSM key pair", "operationId": "createAccount", "description": "Generates an Ed25519 key pair on the HSM partition. Returns the Zetrix address and raw public key hex. The returned address is used as the identifier for subsequent sign requests.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HsmCreateAccountReqDto" } } } }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperHsmCreateAccountRespDto" } } } } } } }, "/ztx/hsm/sign-blob": { "post": { "tags": ["HSM"], "summary": "Sign blob with HSM", "operationId": "signBlobHsm", "description": "Signs a hex-encoded transaction blob using the HSM-stored Ed25519 private key identified by the Zetrix address. The returned SignerEntity can be used directly in /tx/submit or /contract/submit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HsmBlobDataReqDto" } } } }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperListSignerEntity" } } } } } } }, "/ztx/hsm/sign-message": { "post": { "tags": ["HSM"], "summary": "Sign message with HSM", "operationId": "signMessageHsm", "description": "Signs a UTF-8 message using the HSM-stored Ed25519 private key identified by the Zetrix address.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HsmMessageDataReqDto" } } } }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWrapperListSignerEntity" } } } } } } }, "/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" }, "example": "my-token-contract" }, { "name": "method", "in": "query", "required": false, "description": "Filter by contract method name.", "schema": { "type": "string" }, "example": "transfer" }, { "name": "txInitiator", "in": "query", "required": false, "description": "Filter by transaction initiator address.", "schema": { "type": "string" }, "example": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU" }, { "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" }, "example": { "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" } } } } } } } }, "components": { "schemas": { "HsmCreateAccountReqDto": { "type": "object", "description": "Request to create an HSM-backed Ed25519 key pair", "properties": { "label": { "type": "string", "description": "Optional caller-supplied label suffix. Final key label = ZETRIX_