API reference

Contracts and automation reference

Register EVM contracts or Solana programs, publish constrained actions, run backend queries, and track execution history through a single contracts surface.

GET/api/v1/businesses/:id/contract-integrationsx-api-keySandbox + live

List contract integrations

List saved EVM ABI and Solana Anchor IDL integrations for the business.

When to use it

Use when rendering the contracts workspace, validating discovered operations, or selecting an integration before querying or executing actions.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-

Success behavior

Each integration includes discovered write and query operations so your system does not need to re-parse the ABI or IDL at runtime.

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "id": "int_123",
      "businessId": "biz_123",
      "name": "Counter program",
      "chain": "sol",
      "interfaceType": "anchor_idl",
      "networkId": "sol-devnet",
      "contractAddress": "11111111111111111111111111111111",
      "programId": "11111111111111111111111111111111",
      "abiHash": "idl_hash_123",
      "status": "active",
      "turnkeySmartContractInterfaceId": null,
      "turnkeyLastSyncedAt": null,
      "turnkeySyncError": null,
      "availableWriteOperations": [
        { "operationKind": "solana_instruction", "name": "increment", "signature": "increment", "selector": "0102030405060708", "stateMutability": "nonpayable", "inputs": [{ "name": "amount", "type": "u32" }], "outputs": [] }
      ],
      "availableQueryOperations": [
        { "operationKind": "solana_account_query", "name": "counterAccount", "signature": "account:counterAccount", "selector": "0807060504030201", "stateMutability": "view", "inputs": [{ "name": "address", "type": "pubkey" }], "outputs": [{ "name": "count", "type": "u32" }] }
      ]
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/contract-integrations" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key"

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/contract-integrations', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
  },
});
const payload = await response.json();
console.log(payload);

POST/api/v1/businesses/:id/contract-integrationsDashboard UI onlySandbox + live

Create contract integration

Create an EVM contract or Solana program integration and persist discovered operations.

When to use it

Use in the operator setup flow when registering a contract address + ABI or program ID + Anchor IDL before publishing actions.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
name	body	Yes	Operator-facing integration label.	-
chain	body	Yes	Use `eth` for EVM or `sol` for Solana.	-
networkId	body	Yes	Supported target network ID.	-
contractAddress	body	No	Required when `chain=eth`.	-
abiJson	body	No	Required when `chain=eth`; raw ABI JSON array or `{ abi: [...] }` object.	-
programId	body	No	Required when `chain=sol`.	-
idlJson	body	No	Required when `chain=sol`; Anchor IDL JSON.	-
notes	body	No	Optional operator notes.	-

Cautions

Solana support is Anchor IDL only in v1.
Creating an integration stores interface metadata but does not broadcast any on-chain transaction.
This action is dashboard-only and requires recent step-up authentication.

Common errors

401: Missing or invalid API key.
403: The caller is missing the required permission or auth mode for this action.
400: Payload shape, query params, or business-state validation failed.

Sample request body

json

{
  "name": "Counter program",
  "chain": "sol",
  "networkId": "sol-devnet",
  "programId": "11111111111111111111111111111111",
  "idlJson": {
    "version": "0.1.0",
    "name": "counter",
    "instructions": [
      {
        "name": "increment",
        "accounts": [
          { "name": "authority", "isMut": false, "isSigner": true },
          { "name": "counter", "isMut": true, "isSigner": false },
          { "name": "systemProgram", "isMut": false, "isSigner": false }
        ],
        "args": [{ "name": "amount", "type": "u32" }]
      }
    ],
    "accounts": [
      {
        "name": "counterAccount",
        "type": {
          "kind": "struct",
          "fields": [
            { "name": "count", "type": "u32" },
            { "name": "authority", "type": "publicKey" }
          ]
        }
      }
    ]
  }
}

Sample response

json

{
  "integration": {
    "id": "int_123",
    "businessId": "biz_123",
    "name": "Counter program",
    "chain": "sol",
    "interfaceType": "anchor_idl",
    "networkId": "sol-devnet",
    "contractAddress": "11111111111111111111111111111111",
    "programId": "11111111111111111111111111111111",
    "abiHash": "idl_hash_123",
    "notes": null,
    "status": "active",
    "turnkeySmartContractInterfaceId": null,
    "turnkeyLastSyncedAt": null,
    "turnkeySyncError": null,
    "availableFunctions": [
      {
        "operationKind": "solana_instruction",
        "name": "increment",
        "signature": "increment",
        "selector": "0102030405060708",
        "stateMutability": "nonpayable",
        "inputs": [{ "name": "amount", "type": "u32" }],
        "outputs": [],
        "accounts": [
          { "name": "authority", "isWritable": false, "isSigner": true, "optional": false, "fixedAddress": null },
          { "name": "counter", "isWritable": true, "isSigner": false, "optional": false, "fixedAddress": null }
        ]
      }
    ],
    "availableReadFunctions": [
      {
        "operationKind": "solana_account_query",
        "name": "counterAccount",
        "signature": "account:counterAccount",
        "selector": "0807060504030201",
        "stateMutability": "view",
        "inputs": [{ "name": "address", "type": "pubkey" }],
        "outputs": [
          { "name": "count", "type": "u32" },
          { "name": "authority", "type": "pubkey" }
        ]
      }
    ],
    "availableWriteOperations": [],
    "availableQueryOperations": [],
    "createdAt": "2026-04-03T00:12:00.000Z",
    "updatedAt": "2026-04-03T00:12:00.000Z"
  }
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/businesses/biz_123/contract-integrations" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Counter program",
  "chain": "sol",
  "networkId": "sol-devnet",
  "programId": "11111111111111111111111111111111",
  "idlJson": {
    "version": "0.1.0",
    "name": "counter",
    "instructions": [
      {
        "name": "increment",
        "accounts": [
          { "name": "authority", "isMut": false, "isSigner": true },
          { "name": "counter", "isMut": true, "isSigner": false },
          { "name": "systemProgram", "isMut": false, "isSigner": false }
        ],
        "args": [{ "name": "amount", "type": "u32" }]
      }
    ],
    "accounts": [
      {
        "name": "counterAccount",
        "type": {
          "kind": "struct",
          "fields": [
            { "name": "count", "type": "u32" },
            { "name": "authority", "type": "publicKey" }
          ]
        }
      }
    ]
  }
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/contract-integrations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "Counter program",
  "chain": "sol",
  "networkId": "sol-devnet",
  "programId": "11111111111111111111111111111111",
  "idlJson": {
    "version": "0.1.0",
    "name": "counter",
    "instructions": [
      {
        "name": "increment",
        "accounts": [
          { "name": "authority", "isMut": false, "isSigner": true },
          { "name": "counter", "isMut": true, "isSigner": false },
          { "name": "systemProgram", "isMut": false, "isSigner": false }
        ],
        "args": [{ "name": "amount", "type": "u32" }]
      }
    ],
    "accounts": [
      {
        "name": "counterAccount",
        "type": {
          "kind": "struct",
          "fields": [
            { "name": "count", "type": "u32" },
            { "name": "authority", "type": "publicKey" }
          ]
        }
      }
    ]
  }
}),
});
const payload = await response.json();
console.log(payload);

GET/api/v1/businesses/:id/contract-actionsx-api-keySandbox + live

List published contract actions

List published actions that can later be quoted or executed.

When to use it

Use when selecting an action for server-side execution or when reviewing the currently active automation surface.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "id": "act_123",
      "businessId": "biz_123",
      "integrationId": "int_123",
      "name": "Increment counter",
      "description": "Raise the shared counter by a runtime amount.",
      "chain": "sol",
      "operationKind": "solana_instruction",
      "networkId": "sol-devnet",
      "contractAddress": "11111111111111111111111111111111",
      "functionName": "increment",
      "functionSignature": "increment",
      "functionSelector": "0102030405060708",
      "instructionName": "increment",
      "status": "active",
      "version": 1
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/contract-actions" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key"

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/contract-actions', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
  },
});
const payload = await response.json();
console.log(payload);

POST/api/v1/businesses/:id/contract-integrations/:integrationId/actionsDashboard UI onlySandbox + live

Publish contract action

Publish a constrained action from a saved integration.

When to use it

Use after reviewing discovered methods or instructions and before handing controlled execution over to your backend.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
integrationId	path	Yes	Integration ID.	-
name	body	Yes	Action label shown to operators and logs.	-
functionSignature	body	No	Required for EVM integrations.	-
instructionName	body	No	Required for Solana integrations.	-
inputs	body	No	Runtime or fixed input mapping rules.	-
accountMappings	body	No	Solana-only account resolution rules.	-
simulationEnabled	body	No	Solana-only preflight simulation toggle.	-

Cautions

Solana v1 supports single-business-signer instructions only.
Publishing is dashboard-only; API keys execute already published actions instead of creating them.
Keep runtime controls narrow so backend automation cannot drift into arbitrary calldata or account resolution.

Common errors

401: Missing or invalid API key.
403: The caller is missing the required permission or auth mode for this action.
400: Payload shape, query params, or business-state validation failed.
404: Requested resource does not exist or is not owned by the business.

Sample request body

json

{
  "name": "Increment counter",
  "description": "Raise the shared counter by a runtime amount.",
  "instructionName": "increment",
  "inputs": [
    {
      "paramName": "amount",
      "mode": "runtime",
      "runtimeKey": "amount",
      "label": "Amount"
    }
  ],
  "accountMappings": [
    { "accountName": "authority", "mode": "treasury" },
    {
      "accountName": "counter",
      "mode": "runtime",
      "runtimeKey": "counterAddress",
      "label": "Counter account"
    },
    {
      "accountName": "systemProgram",
      "mode": "fixed",
      "fixedAddress": "11111111111111111111111111111111"
    }
  ],
  "simulationEnabled": true,
  "activate": true
}

Sample response

json

{
  "action": {
    "id": "act_123",
    "businessId": "biz_123",
    "integrationId": "int_123",
    "name": "Increment counter",
    "description": "Raise the shared counter by a runtime amount.",
    "chain": "sol",
    "operationKind": "solana_instruction",
    "networkId": "sol-devnet",
    "contractAddress": "11111111111111111111111111111111",
    "functionName": "increment",
    "functionSignature": "increment",
    "functionSelector": "0102030405060708",
    "instructionName": "increment",
    "status": "active",
    "version": 1,
    "createdAt": "2026-04-03T00:14:00.000Z",
    "updatedAt": "2026-04-03T00:14:00.000Z"
  }
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/businesses/biz_123/contract-integrations/int_123/actions" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Increment counter",
  "description": "Raise the shared counter by a runtime amount.",
  "instructionName": "increment",
  "inputs": [
    {
      "paramName": "amount",
      "mode": "runtime",
      "runtimeKey": "amount",
      "label": "Amount"
    }
  ],
  "accountMappings": [
    { "accountName": "authority", "mode": "treasury" },
    {
      "accountName": "counter",
      "mode": "runtime",
      "runtimeKey": "counterAddress",
      "label": "Counter account"
    },
    {
      "accountName": "systemProgram",
      "mode": "fixed",
      "fixedAddress": "11111111111111111111111111111111"
    }
  ],
  "simulationEnabled": true,
  "activate": true
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/contract-integrations/int_123/actions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "Increment counter",
  "description": "Raise the shared counter by a runtime amount.",
  "instructionName": "increment",
  "inputs": [
    {
      "paramName": "amount",
      "mode": "runtime",
      "runtimeKey": "amount",
      "label": "Amount"
    }
  ],
  "accountMappings": [
    { "accountName": "authority", "mode": "treasury" },
    {
      "accountName": "counter",
      "mode": "runtime",
      "runtimeKey": "counterAddress",
      "label": "Counter account"
    },
    {
      "accountName": "systemProgram",
      "mode": "fixed",
      "fixedAddress": "11111111111111111111111111111111"
    }
  ],
  "simulationEnabled": true,
  "activate": true
}),
});
const payload = await response.json();
console.log(payload);

POST/api/v1/contract-integrations/:integrationId/queryx-api-keySandbox + live

Run contract query

Run a read-only query against a saved integration.

When to use it

Use from your backend for EVM view or pure reads, Solana decoded account reads, or unsigned Solana instruction simulations.

Field	Location	Required	Description	Example / default
integrationId	path	Yes	Integration ID.	-
functionSignature	body	No	Required for EVM queries.	-
args	body	No	Optional argument map for EVM or Solana simulation queries.	-
operationKind	body	No	Use `solana_account_query` or `solana_instruction_simulation` for Solana.	-
accountName	body	No	Required for Solana account queries.	-
address	body	No	Required for Solana account queries.	-
instructionName	body	No	Required for Solana instruction simulation.	-
accounts	body	No	Optional Solana instruction simulation account map.	-

Cautions

Use the saved integration surface instead of raw arbitrary calldata so runtime behavior stays constrained.
Solana instruction simulation is unsigned and read-only; it does not publish a transaction.

Common errors

401: Missing or invalid API key.
403: The caller is missing the required permission or auth mode for this action.
400: Payload shape, query params, or business-state validation failed.
404: Requested resource does not exist or is not owned by the business.

Sample request body

json

{
  "operationKind": "solana_account_query",
  "accountName": "counterAccount",
  "address": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
}

Sample response

json

{
  "integration": {
    "id": "int_123",
    "businessId": "biz_123",
    "name": "Counter program",
    "chain": "sol",
    "networkId": "sol-devnet",
    "contractAddress": "11111111111111111111111111111111",
    "status": "active"
  },
  "view": {
    "operationKind": "solana_account_query",
    "name": "counterAccount",
    "signature": "account:counterAccount",
    "selector": "0807060504030201",
    "stateMutability": "view",
    "inputs": [{ "name": "address", "type": "pubkey" }],
    "outputs": [
      { "name": "count", "type": "u32" },
      { "name": "authority", "type": "pubkey" }
    ]
  },
  "request": {
    "queryType": "solana_account_query",
    "args": [],
    "accounts": [
      { "name": "address", "value": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp" }
    ]
  },
  "result": {
    "rawReturnData": "base64:AAkAAAAAAAAA",
    "outputs": [
      { "name": "count", "type": "u32", "value": 9 },
      {
        "name": "authority",
        "type": "pubkey",
        "value": "So11111111111111111111111111111111111111112"
      }
    ],
    "named": {
      "count": 9,
      "authority": "So11111111111111111111111111111111111111112"
    }
  }
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/contract-integrations/int_123/query" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key" \
  -d '{
  "operationKind": "solana_account_query",
  "accountName": "counterAccount",
  "address": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/contract-integrations/int_123/query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
  },
  body: JSON.stringify({
  "operationKind": "solana_account_query",
  "accountName": "counterAccount",
  "address": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
}),
});
const payload = await response.json();
console.log(payload);

GET/api/v1/businesses/:id/contract-executionsx-api-keySandbox + live

List contract executions

List execution attempts for published actions.

When to use it

Use for execution history tables, polling fallbacks, or backend reconciliation after you queue contract actions.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
status	query	No	Optional execution status filter.	-
actionId	query	No	Optional published action filter.	-
page	query	No	Page number.	1
limit	query	No	Page size.	20

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "id": "exe_123",
      "businessId": "biz_123",
      "actionId": "act_123",
      "integrationId": "int_123",
      "idempotencyKey": "contract-exec-001",
      "userReference": "counter-42",
      "txHash": "solana-signature-123",
      "status": "broadcasted",
      "queuedAt": "2026-04-03T00:16:00.000Z",
      "createdAt": "2026-04-03T00:16:00.000Z",
      "updatedAt": "2026-04-03T00:16:03.000Z",
      "action": {
        "id": "act_123",
        "name": "Increment counter",
        "functionSignature": "increment",
        "contractAddress": "11111111111111111111111111111111",
        "networkId": "sol-devnet",
        "chain": "sol",
        "operationKind": "solana_instruction",
        "instructionName": "increment"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasMore": false
  }
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/contract-executions?page=1&limit=20" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key"

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/contract-executions?page=1&limit=20', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
  },
});
const payload = await response.json();
console.log(payload);

POST/api/v1/contract-actions/:actionId/quotex-api-keySandbox + live

Quote published contract action

Prepare and simulate a published action without broadcasting it.

When to use it

Use before execute when you want resolved arguments, recipient or account expansion, and chain-specific preview metadata.

Field	Location	Required	Description	Example / default
actionId	path	Yes	Published action ID.	-
userReference	body	No	Your traceable business reference.	-
recipientAddress	body	No	Recipient address when the action requires one.	-
runtimeArgs	body	No	Runtime arguments keyed by the published action schema.	-
nativeValue	body	No	Optional EVM native value in wei-like raw units.	-
idempotencyKey	body	No	Optional replay-safe execution key.	-

Success behavior

The quote response returns the normalized action plus a chain-specific preview payload, including Solana simulation logs when available.

Common errors

401: Missing or invalid API key.
403: The caller is missing the required permission or auth mode for this action.
403 CONTRACT_API_KEY_POLICY_REJECTED: A contract execution API key attempted an action outside its allowed action, network, contract, or function policy.
400: Payload shape, query params, or business-state validation failed.
404: Requested resource does not exist or is not owned by the business.

Sample request body

json

{
  "userReference": "counter-42",
  "runtimeArgs": {
    "amount": 7,
    "counterAddress": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
  },
  "idempotencyKey": "contract-exec-001"
}

Sample response

json

{
  "action": {
    "id": "act_123",
    "name": "Increment counter",
    "chain": "sol",
    "operationKind": "solana_instruction",
    "networkId": "sol-devnet",
    "contractAddress": "11111111111111111111111111111111",
    "functionSignature": "increment",
    "instructionName": "increment",
    "status": "active"
  },
  "quote": {
    "actionId": "act_123",
    "chain": "sol",
    "networkId": "sol-devnet",
    "programId": "11111111111111111111111111111111",
    "instructionName": "increment",
    "resolvedArgs": [
      { "name": "amount", "type": "u32", "value": 7, "source": "runtime:amount" }
    ],
    "resolvedAccounts": [
      {
        "name": "authority",
        "value": "So11111111111111111111111111111111111111112",
        "source": "treasury"
      },
      {
        "name": "counter",
        "value": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp",
        "source": "runtime:counterAddress"
      }
    ],
    "simulation": {
      "err": null,
      "unitsConsumed": 1234
    },
    "simulationLogs": ["Program log: increment"]
  }
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/contract-actions/act_123/quote" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key" \
  -d '{
  "userReference": "counter-42",
  "runtimeArgs": {
    "amount": 7,
    "counterAddress": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
  },
  "idempotencyKey": "contract-exec-001"
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/contract-actions/act_123/quote', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
  },
  body: JSON.stringify({
  "userReference": "counter-42",
  "runtimeArgs": {
    "amount": 7,
    "counterAddress": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
  },
  "idempotencyKey": "contract-exec-001"
}),
});
const payload = await response.json();
console.log(payload);

POST/api/v1/contract-actions/:actionId/executex-api-keySandbox + live

Execute published contract action

Sign and execute a published contract action asynchronously.

When to use it

Use from your backend once runtime values are ready and your application has accepted the side effect.

Idempotency: recommended

Field	Location	Required	Description	Example / default
actionId	path	Yes	Published action ID.	-
userReference	body	No	Your traceable business reference.	-
recipientAddress	body	No	Recipient address when the action requires one.	-
runtimeArgs	body	No	Runtime arguments keyed by the published action schema.	-
nativeValue	body	No	Optional EVM native value in wei-like raw units.	-
idempotencyKey	body	No	Strongly recommended replay-safe execution key.	-

Cautions

Execution is asynchronous; persist the returned execution ID and treat the initial `202` response as accepted, not confirmed.
Use your own idempotencyKey whenever retries could otherwise duplicate a side effect.
Standard API keys return `HIGH_RISK_API_KEY_SCOPE_DISABLED`; use a dedicated contract execution API key scoped to the action IDs.

Common errors

401: Missing or invalid API key.
403: The caller is missing the required permission or auth mode for this action.
403 HIGH_RISK_API_KEY_SCOPE_DISABLED: A standard API key attempted a protected operation that now requires dashboard session auth or a dedicated payout or contract execution API key.
403 CONTRACT_API_KEY_POLICY_REJECTED: A contract execution API key attempted an action outside its allowed action, network, contract, or function policy.
400: Payload shape, query params, or business-state validation failed.
404: Requested resource does not exist or is not owned by the business.

Sample request body

json

{
  "userReference": "counter-42",
  "runtimeArgs": {
    "amount": 7,
    "counterAddress": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
  },
  "idempotencyKey": "contract-exec-001"
}

Sample response

json

{
  "execution": {
    "id": "exe_123",
    "businessId": "biz_123",
    "actionId": "act_123",
    "integrationId": "int_123",
    "apiKeyId": "key_123",
    "requestedByUserId": null,
    "idempotencyKey": "contract-exec-001",
    "userReference": "counter-42",
    "recipientAddress": null,
    "runtimeArgs": {
      "amount": 7,
      "counterAddress": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
    },
    "resolvedArgs": [
      { "name": "amount", "type": "u32", "value": 7, "source": "runtime:amount" }
    ],
    "resolvedAccounts": [
      {
        "name": "authority",
        "value": "So11111111111111111111111111111111111111112",
        "source": "treasury"
      },
      {
        "name": "counter",
        "value": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp",
        "source": "runtime:counterAddress"
      }
    ],
    "preview": {
      "instructionName": "increment"
    },
    "simulationResult": {
      "err": null,
      "unitsConsumed": 1234
    },
    "simulationLogs": ["Program log: increment"],
    "transactionEncoding": "solana_legacy",
    "unsignedTransaction": "AQABAgM=",
    "signedTransaction": null,
    "txHash": "solana-signature-123",
    "status": "broadcasted",
    "errorCode": null,
    "errorMessage": null,
    "failureDetails": null,
    "queuedAt": "2026-04-03T00:16:00.000Z",
    "simulatedAt": "2026-04-03T00:16:01.000Z",
    "signedAt": "2026-04-03T00:16:02.000Z",
    "broadcastedAt": "2026-04-03T00:16:03.000Z",
    "confirmedAt": null,
    "createdAt": "2026-04-03T00:16:00.000Z",
    "updatedAt": "2026-04-03T00:16:03.000Z",
    "action": {
      "id": "act_123",
      "name": "Increment counter",
      "functionSignature": "increment",
      "contractAddress": "11111111111111111111111111111111",
      "networkId": "sol-devnet",
      "chain": "sol",
      "operationKind": "solana_instruction",
      "instructionName": "increment"
    }
  },
  "replayed": false
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/contract-actions/act_123/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key" \
  -H "Idempotency-Key: example-request-001" \
  -d '{
  "userReference": "counter-42",
  "runtimeArgs": {
    "amount": 7,
    "counterAddress": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
  },
  "idempotencyKey": "contract-exec-001"
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/contract-actions/act_123/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
    'Idempotency-Key': 'example-request-001',
  },
  body: JSON.stringify({
  "userReference": "counter-42",
  "runtimeArgs": {
    "amount": 7,
    "counterAddress": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
  },
  "idempotencyKey": "contract-exec-001"
}),
});
const payload = await response.json();
console.log(payload);

GET/api/v1/contract-executions/:idx-api-keySandbox + live

Get contract execution detail

Return one execution record with resolved args, preview, simulation, and final transaction metadata.

When to use it

Use after quote or execute to poll non-terminal actions or fetch logs for support, analytics, and audit trails.

Field	Location	Required	Description	Example / default
id	path	Yes	Execution ID.	-

Common errors

401: Missing or invalid API key.
403: The caller is missing the required permission or auth mode for this action.
404: Requested resource does not exist or is not owned by the business.

Sample response

json

{
  "execution": {
    "id": "exe_123",
    "businessId": "biz_123",
    "actionId": "act_123",
    "integrationId": "int_123",
    "apiKeyId": "key_123",
    "requestedByUserId": null,
    "idempotencyKey": "contract-exec-001",
    "userReference": "counter-42",
    "recipientAddress": null,
    "runtimeArgs": {
      "amount": 7,
      "counterAddress": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp"
    },
    "resolvedArgs": [
      { "name": "amount", "type": "u32", "value": 7, "source": "runtime:amount" }
    ],
    "resolvedAccounts": [
      {
        "name": "authority",
        "value": "So11111111111111111111111111111111111111112",
        "source": "treasury"
      },
      {
        "name": "counter",
        "value": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp",
        "source": "runtime:counterAddress"
      }
    ],
    "preview": {
      "instructionName": "increment"
    },
    "simulationResult": {
      "err": null,
      "unitsConsumed": 1234
    },
    "simulationLogs": ["Program log: increment"],
    "transactionEncoding": "solana_legacy",
    "unsignedTransaction": "AQABAgM=",
    "signedTransaction": null,
    "txHash": "solana-signature-123",
    "status": "broadcasted",
    "errorCode": null,
    "errorMessage": null,
    "failureDetails": null,
    "queuedAt": "2026-04-03T00:16:00.000Z",
    "simulatedAt": "2026-04-03T00:16:01.000Z",
    "signedAt": "2026-04-03T00:16:02.000Z",
    "broadcastedAt": "2026-04-03T00:16:03.000Z",
    "confirmedAt": null,
    "createdAt": "2026-04-03T00:16:00.000Z",
    "updatedAt": "2026-04-03T00:16:03.000Z",
    "action": {
      "id": "act_123",
      "name": "Increment counter",
      "functionSignature": "increment",
      "contractAddress": "11111111111111111111111111111111",
      "networkId": "sol-devnet",
      "chain": "sol",
      "operationKind": "solana_instruction",
      "instructionName": "increment"
    }
  },
  "replayed": false
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/contract-executions/biz_123" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key"

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/contract-executions/biz_123', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
  },
});
const payload = await response.json();
console.log(payload);

Withdrawals and treasury reference

Reference data and billing reference