API reference

Business identity reference

Read the authenticated business record or resolve a billing alias before connecting downstream systems.

GET/api/v1/businesses/:idx-api-keySandbox + live

Get business details

Return the authenticated business record.

When to use it

Use to confirm identity, billing alias, and top-level business status.

Idempotency: not applicable

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

Common errors

401: Missing or invalid API key.
404: Requested resource does not exist or is not owned by the business.

Sample response

json

{
  "id": "biz_123",
  "billingAlias": "bill_acme_001",
  "name": "Acme Treasury",
  "status": "active",
  "treasuryAddress": "0x1b2c3d4e5f6789012345678901234567890abced",
  "createdAt": "2026-03-10T11:00:00.000Z",
  "updatedAt": "2026-03-14T09:20:00.000Z"
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/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/businesses/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);

GET/api/v1/businesses/lookup/:idOrAliasx-api-keySandbox + live

Look up business by ID or billing alias

Resolve a business identity for validation flows.

When to use it

Use when you need to validate a business alias before attaching it to downstream workflows.

Idempotency: not applicable

Field	Location	Required	Description	Example / default
idOrAlias	path	Yes	Business ID or `bill_*` alias.	bill_acme_001

Common errors

401: Missing or invalid API key.
404: Requested resource does not exist or is not owned by the business.

Sample response

json

{
  "id": "biz_123",
  "billingAlias": "bill_acme_001",
  "name": "Acme Treasury",
  "status": "active"
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/lookup/bill_acme_001" \
  -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/lookup/bill_acme_001', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
  },
});
const payload = await response.json();
console.log(payload);

GET/api/v1/businesses/:id/api-keysDashboard UI onlySandbox + live

List API keys

List active standard and payout API keys for a business without exposing key material.

When to use it

Use in dashboard settings or operator tooling to audit active credentials and payout policies.

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

Cautions

Plaintext API keys are shown only once at creation time.
Payout key policy is returned for operator review, but the secret value is never returned.

Common errors

401: Missing or invalid API key.
403: The caller is missing the required permission or auth mode for this action.

Sample response

json

[
  {
    "id": "key_123",
    "name": "Production invoices server",
    "kind": "standard",
    "permissions": [
      "business:read",
      "customers:*",
      "invoices:*",
      "payments:read",
      "events:read"
    ],
    "lastUsedAt": "2026-03-14T09:12:04.000Z",
    "expiresAt": "2026-06-12T15:30:00.000Z",
    "createdAt": "2026-03-12T15:30:00.000Z",
    "payoutPolicy": null
  },
  {
    "id": "key_payout_123",
    "name": "Vendor payouts",
    "kind": "payout",
    "permissions": ["payouts:create", "payouts:read"],
    "lastUsedAt": null,
    "expiresAt": "2026-04-11T15:30:00.000Z",
    "createdAt": "2026-03-12T15:35:00.000Z",
    "payoutPolicy": {
      "destinationPolicy": "allowlist",
      "allowedDestinations": [
        {
          "chain": "sol",
          "address": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp",
          "label": "Solana operations wallet"
        }
      ],
      "allowedChains": ["sol", "eth"],
      "allowedNetworkIds": ["sol-mainnet", "base-mainnet"],
      "allowedTokens": ["USDC"],
      "limits": [
        {
          "chain": "sol",
          "networkId": "sol-mainnet",
          "token": "USDC",
          "maxAmount": "1000",
          "dailyAmount": "5000"
        }
      ],
      "ipAllowlist": ["203.0.113.10/32"]
    }
  }
]

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/api-keys" \
  -H "Content-Type: application/json"

Node.js example

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

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

Create standard API key

Create a server-side standard API key for invoices, customers, reads, and non-fund-moving automation.

When to use it

Use from the dashboard after step-up when provisioning backend integrations that should not move treasury funds.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
name	body	Yes	Operator label for this key.	-
permissions	body	No	Allowed standard permissions. Wildcards for high-risk families and payout permissions are rejected.	-
expiresIn	body	No	Optional key lifetime in days, max 365.	-

Cautions

The plaintext `apiKey` is returned once. Store it in a server-side secret manager immediately.
Standard API keys cannot create, rotate, or revoke API keys and cannot create withdrawals.
`*`, `apiKeys:*`, `payments:*`, `payouts:create`, and contract signing permissions are rejected for standard keys.

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.
400 HIGH_RISK_SCOPE_NOT_ALLOWED: Requested permission is not allowed on a standard API key.

Sample request body

json

{
  "name": "Production invoices server",
  "permissions": [
    "business:read",
    "customers:*",
    "invoices:*",
    "payments:read",
    "events:read"
  ],
  "expiresIn": 90
}

Sample response

json

{
  "id": "key_123",
  "name": "Production invoices server",
  "kind": "standard",
  "apiKey": "biz_live_1234567890abcdef",
  "permissions": [
    "business:read",
    "customers:*",
    "invoices:*",
    "payments:read",
    "events:read"
  ],
  "expiresAt": "2026-06-12T15:30:00.000Z",
  "createdAt": "2026-03-12T15:30:00.000Z",
  "warning": "Store this API key securely. It cannot be recovered."
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/businesses/biz_123/api-keys" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production invoices server",
  "permissions": [
    "business:read",
    "customers:*",
    "invoices:*",
    "payments:read",
    "events:read"
  ],
  "expiresIn": 90
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/api-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "Production invoices server",
  "permissions": [
    "business:read",
    "customers:*",
    "invoices:*",
    "payments:read",
    "events:read"
  ],
  "expiresIn": 90
}),
});
const payload = await response.json();
console.log(payload);

POST/api/v1/businesses/:id/payout-api-keysDashboard UI onlySandbox + live

Create payout API key

Create a dedicated payout API key with allowlisted or dynamic destinations within configured limits.

When to use it

Use when a backend needs programmatic withdrawals after you have defined destination policy, token, network, spend, and optional IP guardrails.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
name	body	Yes	Operator label for this payout key.	-
destinationPolicy	body	No	`allowlist` by default. Set to `any` to allow withdrawals to any valid destination while still enforcing token, network, spend, and optional IP limits.	-
destinations	body	No	Allowed withdrawal destinations, each with `chain`, `address`, and optional `label`. Required when `destinationPolicy` is `allowlist`.	-
limits	body	Yes	Allowed `chain`, `networkId`, `token`, `maxAmount` per withdrawal, and rolling `dailyAmount`.	-
ipAllowlist	body	No	Optional IPv4 addresses or CIDR blocks that may use this key.	-
expiresIn	body	No	Optional key lifetime in days, max 365.	-

Cautions

Payout keys cannot create dashboard sessions, manage API keys, or bypass the configured payout policy.
`destinationPolicy: any` increases payout-key blast radius; use lower limits, shorter expiry, and IP allowlists when possible.
The withdrawal request still needs an `Idempotency-Key`; policy approval is not a settlement guarantee.
Rotate payout keys separately from standard API keys because the blast radius and alerting profile are different.

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": "Vendor payouts",
  "expiresIn": 30,
  "destinationPolicy": "allowlist",
  "destinations": [
    {
      "chain": "sol",
      "address": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp",
      "label": "Solana operations wallet"
    },
    {
      "chain": "eth",
      "address": "0x5fBDB2315678afecb367f032d93F642f64180aa3",
      "label": "Base operations wallet"
    }
  ],
  "limits": [
    {
      "chain": "sol",
      "networkId": "sol-mainnet",
      "token": "USDC",
      "maxAmount": "1000",
      "dailyAmount": "5000"
    },
    {
      "chain": "eth",
      "networkId": "base-mainnet",
      "token": "USDC",
      "maxAmount": "1000",
      "dailyAmount": "5000"
    }
  ],
  "ipAllowlist": ["203.0.113.10/32"]
}

Sample response

json

{
  "id": "key_payout_123",
  "name": "Vendor payouts",
  "kind": "payout",
  "apiKey": "biz_live_payout_1234567890abcdef",
  "permissions": ["payouts:create", "payouts:read"],
  "expiresAt": "2026-04-11T15:35:00.000Z",
  "createdAt": "2026-03-12T15:35:00.000Z",
  "policy": {
    "destinationPolicy": "allowlist",
    "destinations": [
      {
        "chain": "sol",
        "address": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp",
        "label": "Solana operations wallet"
      }
    ],
    "allowedChains": ["sol", "eth"],
    "allowedNetworkIds": ["sol-mainnet", "base-mainnet"],
    "allowedTokens": ["USDC"],
    "limits": [
      {
        "chain": "sol",
        "networkId": "sol-mainnet",
        "token": "USDC",
        "maxAmount": "1000",
        "dailyAmount": "5000"
      }
    ],
    "ipAllowlist": ["203.0.113.10/32"]
  },
  "warning": "Store this payout API key securely. It can create withdrawals only within the configured policy and cannot be recovered."
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/businesses/biz_123/payout-api-keys" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Vendor payouts",
  "expiresIn": 30,
  "destinationPolicy": "allowlist",
  "destinations": [
    {
      "chain": "sol",
      "address": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp",
      "label": "Solana operations wallet"
    },
    {
      "chain": "eth",
      "address": "0x5fBDB2315678afecb367f032d93F642f64180aa3",
      "label": "Base operations wallet"
    }
  ],
  "limits": [
    {
      "chain": "sol",
      "networkId": "sol-mainnet",
      "token": "USDC",
      "maxAmount": "1000",
      "dailyAmount": "5000"
    },
    {
      "chain": "eth",
      "networkId": "base-mainnet",
      "token": "USDC",
      "maxAmount": "1000",
      "dailyAmount": "5000"
    }
  ],
  "ipAllowlist": ["203.0.113.10/32"]
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/payout-api-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "Vendor payouts",
  "expiresIn": 30,
  "destinationPolicy": "allowlist",
  "destinations": [
    {
      "chain": "sol",
      "address": "8gRLe6GiQx2jo9mQFcbwy34u2W4zD2rN5q4mmD8iP2Mp",
      "label": "Solana operations wallet"
    },
    {
      "chain": "eth",
      "address": "0x5fBDB2315678afecb367f032d93F642f64180aa3",
      "label": "Base operations wallet"
    }
  ],
  "limits": [
    {
      "chain": "sol",
      "networkId": "sol-mainnet",
      "token": "USDC",
      "maxAmount": "1000",
      "dailyAmount": "5000"
    },
    {
      "chain": "eth",
      "networkId": "base-mainnet",
      "token": "USDC",
      "maxAmount": "1000",
      "dailyAmount": "5000"
    }
  ],
  "ipAllowlist": ["203.0.113.10/32"]
}),
});
const payload = await response.json();
console.log(payload);

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

Create contract execution API key

Create a dedicated API key that can quote and execute only selected published contract actions.

When to use it

Use when a backend needs real-time buy/sell, approve, or other constrained contract execution without granting broad standard-key signing access.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
name	body	Yes	Operator label for this contract execution key.	-
actionIds	body	Yes	Published active contract action IDs this key may quote and execute.	-
expiresIn	body	No	Optional key lifetime in days, max 365.	-

Cautions

The key stores a policy snapshot of action IDs, networks, contract addresses, and function signatures.
Standard API keys still cannot execute contract actions.
Rotate this key independently from standard and payout keys.

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.
403 CONTRACT_API_KEY_POLICY_REJECTED: A contract execution API key attempted an action outside its allowed action, network, contract, or function policy.

Sample request body

json

{
  "name": "TSTY buy/sell executor",
  "expiresIn": 30,
  "actionIds": [
    "7a8a6b0d-5a18-4c71-9478-18c6a54fe9cb",
    "11e71b3c-88bb-49b2-a1c9-ffce42d62df1"
  ]
}

Sample response

json

{
  "id": "key_contract_123",
  "name": "TSTY buy/sell executor",
  "kind": "contract_execution",
  "apiKey": "biz_live_contract_1234567890abcdef",
  "permissions": ["contracts:sign", "contracts:read"],
  "expiresAt": "2026-04-11T15:35:00.000Z",
  "createdAt": "2026-03-12T15:35:00.000Z",
  "policy": {
    "allowedActionIds": [
      "7a8a6b0d-5a18-4c71-9478-18c6a54fe9cb",
      "11e71b3c-88bb-49b2-a1c9-ffce42d62df1"
    ],
    "allowedNetworkIds": ["bnb-mainnet"],
    "allowedContractAddresses": ["0x00000000000000000000000000000000000000aa"],
    "allowedFunctionSignatures": ["buyTokens(uint256)", "sellTokens(uint256)"]
  },
  "warning": "Store this contract execution API key securely. It can execute only the configured published contract actions and cannot be recovered."
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/businesses/biz_123/contract-api-keys" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "TSTY buy/sell executor",
  "expiresIn": 30,
  "actionIds": [
    "7a8a6b0d-5a18-4c71-9478-18c6a54fe9cb",
    "11e71b3c-88bb-49b2-a1c9-ffce42d62df1"
  ]
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/contract-api-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "TSTY buy/sell executor",
  "expiresIn": 30,
  "actionIds": [
    "7a8a6b0d-5a18-4c71-9478-18c6a54fe9cb",
    "11e71b3c-88bb-49b2-a1c9-ffce42d62df1"
  ]
}),
});
const payload = await response.json();
console.log(payload);

DELETE/api/v1/businesses/:id/api-keys/:keyIdDashboard UI onlySandbox + live

Revoke API key

Revoke a standard or payout API key for a business.

When to use it

Use when a key is no longer needed, an operator leaves, a deployment secret rotates, or policy needs to be tightened.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
keyId	path	Yes	API key ID to revoke.	-

Cautions

Revocation is immediate for future requests. In-flight withdrawal jobs keep their persisted audit metadata.

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

{
  "ok": true
}

cURL example

bash

curl -X DELETE "https://api.paychainhq.io/api/v1/businesses/biz_123/api-keys/key_123" \
  -H "Content-Type: application/json"

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/api-keys/key_123', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
  },
});
const payload = await response.json();
console.log(payload);

Reconcile balances and transactions

Settings and compliance reference