Paymaster

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.

Generate paymaster transaction blob

post

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.

Flow:

1. Call this endpoint with userAddress and operations

2. Receive blob, blobId, and reservation expiry (expiresAt)

3. Sign the blob using /tx/sign-blob

4. Submit via /tx/paymaster/submit within timeoutMinutes

Pool Selection: Auto-selected unless paymasterPoolId or poolType (NORMAL, PREMIUM, CORPORATE) is specified.

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 paymaster-sponsored transaction blob (gas-free for users).

userAddressstringRequired

Zetrix address of the user initiating the transaction. Gas covered by the Paymaster.

Example: ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU

chainCodestringOptional

Chain code identifier. Defaults to "0".

Default: 0Example: 0

paymasterPoolIdinteger · int64Optional

Specific paymaster pool ID. Auto-selected if not provided.

Example: 1

operationTypestringOptional

Operation type label for tracking.

Example: TRANSFER

targetAddressstringOptional

Target address for tracking purposes.

Example: ZTX9876543210ZYXWVUTSRQPONMLKJIHGFED

amountstringOptional

Transaction amount for tracking (optional).

Example: 1000000

timeoutMinutesinteger · int32Optional

Minutes the nonce reservation is valid. Defaults to 10.

Default: 10Example: 10

minPoolBalanceinteger · int64Optional

Minimum required pool balance in drops (optional).

Example: 10000000

poolTypestring · enumOptional

Preferred paymaster pool type.

Example: NORMALPossible values:

Responses

200

Paymaster blob generated. Sign and submit via /tx/paymaster/submit before expiresAt.

*/*

successbooleanOptional

timestampstring · date-timeOptional

traceIdstringOptional

post

/ztx/tx/paymaster/generate-blob

HTTPcURLJavaScriptPython

POST /ztx/tx/paymaster/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: 269

{
  "userAddress": "ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU",
  "operations": [
    {
      "type": "SEND_GAS",
      "toAddress": "ZTX3TkqopBiDmHFMEBr5U7n9HfNqBa7LBhV2Q",
      "amount": "1000000"
    }
  ],
  "chainCode": "0",
  "timeoutMinutes": 10,
  "poolType": "NORMAL",
  "metadata": {
    "appId": "mobile-app",
    "version": "1.0.0"
  }
}

200

Paymaster blob generated. Sign and submit via /tx/paymaster/submit before expiresAt.

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

Submit paymaster transaction

post

Submits a signed paymaster transaction blob for asynchronous processing. Returns immediately with QUEUED status.

Pre-conditions:

• blobId from a valid, non-expired /tx/paymaster/generate-blob call

• blob signed by the user's private key

• Submitted before expiresAt

Async Processing: The Paymaster adds its gas-sponsoring signature and broadcasts the transaction. Poll /tx/query with txHash to check final status.

Response Fields:

• status — Initially QUEUED

• txHash — Use this to query the final result

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 body for submitting a paymaster-sponsored transaction or contract invocation.

blobIdstringRequired

Unique ID of the paymaster blob reservation from generate-blob.

Example: 550e8400-e29b-41d4-a716-446655440000

blobstringRequired

The hex-encoded transaction blob returned during blob generation.

Example: 0A255A5458334A64656A33434B7443724253547851747456666E6456...

Responses

200

Transaction queued for paymaster processing. Poll /tx/query using txHash for final status.

*/*

successbooleanOptional

timestampstring · date-timeOptional

traceIdstringOptional

post

/ztx/tx/paymaster/submit

HTTPcURLJavaScriptPython

POST /ztx/tx/paymaster/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: 234

{
  "blobId": "550e8400-e29b-41d4-a716-446655440000",
  "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...",
  "listSigner": [
    {
      "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...",
      "publicKey": "b00179b4adb1d3188aa1b98d6977a837..."
    }
  ]
}

200

Transaction queued for paymaster processing. Poll /tx/query using txHash for final status.

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

Generate paymaster contract invocation blob

post

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.

Flow:

1. Call this endpoint with the user's address, contract identifier, method, and input parameters

2. Receive blob, blobId, and expiry info

3. Sign the blob using /tx/sign-blob

4. Submit via /contract/paymaster/submit before expiresAt

Pool Selection: Auto-selected unless paymasterPoolId or poolType (NORMAL, PREMIUM, CORPORATE) is specified.

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 paymaster-sponsored contract invocation blob.

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

userAddressstring · min: 37 · max: 37Required

User's Zetrix address (initiator). Gas covered by the Paymaster.

Example: ZTX3PGkYe55MJdKLMEQDShy5tR1as7kYJFZbU

valueinteger · int64Optional

ZTX value in drops. Use 0 for non-payable methods.

Example: 0

chainCodestringOptional

Chain code identifier. Defaults to "0".

Default: 0Example: 0

paymasterPoolIdinteger · int64Optional

Specific paymaster pool ID. Auto-selected if not provided.

Example: 1

timeoutMinutesinteger · int32Optional

Nonce reservation timeout in minutes. Defaults to 10.

Default: 10Example: 10

minPoolBalanceinteger · int64Optional

Minimum required paymaster pool balance in drops.

Example: 10000000

poolTypestring · enumOptional

Preferred paymaster pool type.

Example: NORMALPossible values:

Responses

200

Paymaster contract blob generated. Sign and submit via /contract/paymaster/submit before expiry.

*/*

successbooleanOptional

timestampstring · date-timeOptional

traceIdstringOptional

post

/ztx/contract/paymaster/generate-blob

HTTPcURLJavaScriptPython

POST /ztx/contract/paymaster/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: 311

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

200

Paymaster contract blob generated. Sign and submit via /contract/paymaster/submit before expiry.

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

Submit paymaster contract invocation

post

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.

Required fields:

• blobId — from /contract/paymaster/generate-blob

• blob — signed by the user

• listSigner — user's signature(s)

Tracking: Poll /tx/query with txHash to check final 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 body for submitting a paymaster-sponsored transaction or contract invocation.

blobIdstringRequired

Unique ID of the paymaster blob reservation from generate-blob.

Example: 550e8400-e29b-41d4-a716-446655440000

blobstringRequired

The hex-encoded transaction blob returned during blob generation.

Example: 0A255A5458334A64656A33434B7443724253547851747456666E6456...

Responses

200

Contract invocation queued for paymaster processing.

*/*

successbooleanOptional

timestampstring · date-timeOptional

traceIdstringOptional

post

/ztx/contract/paymaster/submit

HTTPcURLJavaScriptPython

POST /ztx/contract/paymaster/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: 234

{
  "blobId": "550e8400-e29b-41d4-a716-446655440000",
  "blob": "0A255A5458334A64656A33434B7443724253547851747456666E6456...",
  "listSigner": [
    {
      "signBlob": "b8f4a2c3d1e0f9a8b7c6d5e4f3a2b1c0...",
      "publicKey": "b00179b4adb1d3188aa1b98d6977a837..."
    }
  ]
}

200

Contract invocation queued for paymaster processing.

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