API reference

Reference data and billing reference

Public and business-scoped market data, supported networks/tokens, and platform billing endpoints.

GET/api/v1/pricesPublicSandbox + live

List prices

Return cached token USD prices.

When to use it

Use for informational displays, not as the sole source of accounting truth.

Common errors

400: Payload shape, query params, or business-state validation failed.

Sample response

json

{
  "data": [
    {
      "symbol": "USDC",
      "usd": "1.000000000000000000",
      "source": "coingecko",
      "stale": false
    }
  ]
}

cURL example

bash

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

Node.js example

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

GET/api/v1/prices/:symbolPublicSandbox + live

Get token price

Return the latest cached USD quote for one token.

When to use it

Use for UI hints or preflight pricing displays.

Field	Location	Required	Description	Example / default
symbol	path	Yes	Token symbol.	USDC

Common errors

404: Requested resource does not exist or is not owned by the business.

Sample response

json

{
  "symbol": "USDC",
  "usd": "1.000000000000000000",
  "pricedAt": "2026-03-14T13:45:00.000Z",
  "source": "coingecko",
  "stale": false,
  "ttlMs": 30000
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/prices/USDC" \
  -H "Content-Type: application/json"

Node.js example

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

GET/api/v1/networksPublicSandbox + live

List supported networks

Return supported networks for invoice and withdrawal operations.

When to use it

Use to populate allowed chain/network selectors in your product.

Cautions

Use runtime network IDs, not human-readable display names, in invoice and withdrawal payloads.

Sample response

json

{
  "data": [
    {
      "networkId": "base-mainnet",
      "name": "Base Mainnet",
      "chain": "eth",
      "type": "MAINNET",
      "isActive": true,
      "depositEnabled": true,
      "minimumDepositUsd": "1.00",
      "dustThresholdUsd": "0.25",
      "supportedTokens": [
        {
          "symbol": "USDC",
          "name": "USD Coin",
          "contractAddress": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
          "decimals": 6,
          "depositEnabled": true
        }
      ]
    }
  ]
}

cURL example

bash

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

Node.js example

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

GET/api/v1/supported-assetsPublicSandbox + live

List supported assets

Return the public deposit rail catalog with network and token metadata.

When to use it

Use before onboarding or cashier rendering to discover supported networks, tokens, decimals, confirmations, and minimum deposit metadata.

Field	Location	Required	Description	Example / default
includeInactive	query	No	Include inactive or disabled rails when true.	false

Cautions

This is the platform catalog. Use the business payment methods endpoint for business-scoped availability.

Sample response

json

{
  "count": 1,
  "paymentMethods": [
    {
      "networkId": "base-mainnet",
      "networkName": "Base Mainnet",
      "displayName": "Base Mainnet",
      "chain": "eth",
      "chainFamily": "eth",
      "networkType": "mainnet",
      "status": "active",
      "depositEnabled": true,
      "customerPermanentAddresses": true,
      "requiredConfirmations": 12,
      "minimumDepositUsd": "1.00",
      "dustThresholdUsd": "0.25",
      "tokens": [
        {
          "symbol": "USDC",
          "name": "USD Coin",
          "contractAddress": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
          "decimals": 6,
          "depositEnabled": true
        }
      ]
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/supported-assets?includeInactive=false" \
  -H "Content-Type: application/json"

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/supported-assets?includeInactive=false', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
  },
});
const payload = await response.json();
console.log(payload);

GET/api/v1/businesses/:id/payment-methodsx-api-keySandbox + live

List business payment methods

Return deposit rails enabled for a specific business and environment.

When to use it

Use in cashier backends to render only the networks and tokens that this business can receive on.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
includeInactive	query	No	Include inactive business rails when true.	false

Common errors

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

Sample response

json

{
  "businessId": "biz_123",
  "count": 1,
  "paymentMethods": [
    {
      "networkId": "base-mainnet",
      "networkName": "Base Mainnet",
      "displayName": "Base Mainnet",
      "chain": "eth",
      "chainFamily": "eth",
      "networkType": "mainnet",
      "status": "active",
      "depositEnabled": true,
      "customerPermanentAddresses": true,
      "requiredConfirmations": 12,
      "minimumDepositUsd": "1.00",
      "dustThresholdUsd": "0.25",
      "tokens": [
        {
          "symbol": "USDC",
          "name": "USD Coin",
          "contractAddress": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
          "decimals": 6,
          "depositEnabled": true
        }
      ]
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/payment-methods?includeInactive=false" \
  -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/payment-methods?includeInactive=false', {
  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/tokensx-api-keySandbox + live

List supported tokens

Return supported tokens visible to the authenticated business.

When to use it

Use for product-side token selectors or validation before invoice creation.

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "symbol": "USDC",
      "name": "USD Coin",
      "chain": "eth",
      "networkId": "base-mainnet",
      "decimals": 6,
      "isActive": true
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/tokens" \
  -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/tokens', {
  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/tokens/networks/:networkIdx-api-keySandbox + live

List tokens by network

Return tokens supported on a single network.

When to use it

Use after the operator selects a network and you want the allowed token subset.

Field	Location	Required	Description	Example / default
networkId	path	Yes	Network ID.	base-mainnet

Common errors

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

Sample response

json

{
  "data": [
    {
      "symbol": "USDC",
      "name": "USD Coin",
      "chain": "eth",
      "networkId": "base-mainnet",
      "decimals": 6,
      "isActive": true
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/tokens/networks/base-mainnet" \
  -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/tokens/networks/base-mainnet', {
  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/tokens/:symbolx-api-keySandbox + live

Get token details

Return details for one supported token.

When to use it

Use when you need token decimals, contract address, or current support status.

Field	Location	Required	Description	Example / default
symbol	path	Yes	Token symbol.	USDC

Common errors

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

Sample response

json

{
  "symbol": "USDC",
  "name": "USD Coin",
  "chain": "eth",
  "networkId": "base-mainnet",
  "decimals": 6,
  "contractAddress": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
  "isActive": true
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/tokens/USDC" \
  -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/tokens/USDC', {
  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/billing/mex-api-keySandbox + live

Get billing profile

Return the current plan, subscription state, and pricing policy.

When to use it

Use in account settings or when reconciling PayChainHQ platform fees.

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "business": {
    "id": "biz_123",
    "activePlanCode": "GROWTH",
    "billingStatus": "active",
    "billingAlias": "bill_acme_001"
  },
  "policy": {
    "planCode": "GROWTH",
    "billingMode": "prepaid_monthly",
    "monthlyFeeUsd": "99.000000000000",
    "annualEligible": true,
    "annualBaseFeeUsd": "1069.200000000000",
    "annualDiscountPercent": 10,
    "invoiceFeeRate": "0.0065000000",
    "linkedPayoutFreeQuota": 500,
    "introActive": false
  },
  "subscription": {
    "id": "sub_123",
    "planCode": "GROWTH",
    "billingMode": "prepaid_annual",
    "status": "active",
    "currentCycleStart": "2026-03-23T09:00:00.000Z",
    "currentCycleEnd": "2026-04-23T09:00:00.000Z",
    "nextBillingAt": "2026-04-23T09:00:00.000Z"
  }
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/billing/me" \
  -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/billing/me', {
  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/billing/plansx-api-keySandbox + live

List billing plans

Return active billing plans with monthly and annual pricing metadata.

When to use it

Use when rendering pricing comparisons, upgrade dialogs, or billing-mode toggles.

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "plans": [
    {
      "code": "FREE",
      "name": "Free",
      "tier": "FREE",
      "monthlyBaseFeeUsd": "0.000000000000",
      "annualEligible": false,
      "annualBaseFeeUsd": null,
      "annualDiscountPercent": null,
      "invoiceFeeRate": "0.0095000000",
      "payoutApiWithdrawalQuota": 0
    },
    {
      "code": "STARTUP",
      "name": "Startup",
      "tier": "STARTUP",
      "monthlyBaseFeeUsd": "19.000000000000",
      "invoiceFeeRate": "0.0070000000",
      "payoutApiWithdrawalQuota": 100
    },
    {
      "code": "GROWTH",
      "name": "Growth",
      "tier": "GROWTH",
      "monthlyBaseFeeUsd": "99.000000000000",
      "annualEligible": false,
      "annualBaseFeeUsd": null,
      "annualDiscountPercent": null,
      "introMonthlyFeeUsd": null,
      "introCycles": 0,
      "invoiceFeeRate": "0.0055000000",
      "payoutApiWithdrawalQuota": 1000
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/billing/plans" \
  -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/billing/plans', {
  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/billing/subscription/changeDashboard UI onlySandbox + live

Request billing subscription change

Request a plan or billing-mode change and receive either a payment invoice or a scheduled downgrade.

When to use it

Use from the operator dashboard when switching between Free, Startup, Growth, Scale, and Enterprise plans.

Idempotency: recommended

Field	Location	Required	Description	Example / default
planCode	body	Yes	Target plan code, for example `GROWTH`.	-
billingMode	body	No	Billing cadence, either `prepaid_monthly` or `prepaid_annual`.	-
networkId	body	No	Optional billing rail network for the upgrade invoice.	-

Cautions

Annual billing is supported only for `GROWTH` in v1.
Downgrades and annual-to-monthly changes are scheduled for the current cycle end.

Common errors

401: Missing or invalid API key.
400: Payload shape, query params, or business-state validation failed.

Sample request body

json

{
  "planCode": "GROWTH",
  "billingMode": "prepaid_monthly",
  "networkId": "base-mainnet"
}

Sample response

json

{
  "state": "payment_required",
  "fromPlanCode": "FREE",
  "toPlanCode": "GROWTH",
  "billingMode": "prepaid_monthly",
  "invoice": {
    "id": "bill_inv_123",
    "status": "pending",
    "amountUsd": "99.000000000000",
    "networkId": "base-mainnet",
    "token": "USDC"
  },
  "paymentInstructions": {
    "networkId": "base-mainnet",
    "token": "USDC",
    "expectedAmountRaw": "1069200000"
  }
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/billing/subscription/change" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-request-001" \
  -d '{
  "planCode": "GROWTH",
  "billingMode": "prepaid_monthly",
  "networkId": "base-mainnet"
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/billing/subscription/change', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': 'example-request-001',
  },
  body: JSON.stringify({
  "planCode": "GROWTH",
  "billingMode": "prepaid_monthly",
  "networkId": "base-mainnet"
}),
});
const payload = await response.json();
console.log(payload);

GET/api/v1/billing/invoicesx-api-keySandbox + live

List billing invoices

Return PayChainHQ subscription / billing invoices for the business.

When to use it

Use when presenting invoice history or outstanding platform charges.

Field	Location	Required	Description	Example / default
status	query	No	Optional billing status filter.	-
limit	query	No	Page size.	20
offset	query	No	Offset for pagination.	0

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "id": "bill_inv_123",
      "status": "open",
      "amountUSD": "245.20",
      "dueAt": "2026-03-20T00:00:00.000Z"
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/billing/invoices?limit=20&offset=0" \
  -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/billing/invoices?limit=20&offset=0', {
  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/billing/usagex-api-keySandbox + live

Get billing usage

Return cycle usage / quota data.

When to use it

Use before linked-payout spikes or when checking plan limits.

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "cycle": {
    "start": "2026-03-01T00:00:00.000Z",
    "end": "2026-03-31T23:59:59.000Z"
  },
  "linkedPayoutUsage": {
    "count": 19,
    "quota": 100
  }
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/billing/usage" \
  -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/billing/usage', {
  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/billing/invoices/:invoiceId/payx-api-keySandbox + live

Attach billing payment

Attach a chain payment to a PayChainHQ billing invoice.

When to use it

Use when settling a platform invoice with an on-chain payment reference.

Idempotency: required

Field	Location	Required	Description	Example / default
invoiceId	path	Yes	Billing invoice ID.	-
chain	body	Yes	Settlement chain family.	-
networkId	body	Yes	Settlement network.	-
txHash	body	Yes	Transaction hash used for payment.	-

Cautions

Replay is deduped by `chain + networkId + txHash`.
Using the same tx hash for another billing invoice produces a replay conflict.

Common errors

401: Missing or invalid API key.
400: Payload shape, query params, or business-state validation failed.
BILLING_PAYMENT_REPLAY_CONFLICT: The tx hash already belongs to a different billing invoice payment.
BILLING_UNDERPAYMENT: Attached payment is below the invoice amount.

Sample request body

json

{
  "chain": "eth",
  "networkId": "base-mainnet",
  "txHash": "0x9ee6b13bdf7d5c7e..."
}

Sample response

json

{
  "ok": true,
  "status": "paid",
  "replayed": false
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/billing/invoices/inv_123/pay" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key" \
  -H "Idempotency-Key: example-request-001" \
  -d '{
  "chain": "eth",
  "networkId": "base-mainnet",
  "txHash": "0x9ee6b13bdf7d5c7e..."
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/billing/invoices/inv_123/pay', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
    'Idempotency-Key': 'example-request-001',
  },
  body: JSON.stringify({
  "chain": "eth",
  "networkId": "base-mainnet",
  "txHash": "0x9ee6b13bdf7d5c7e..."
}),
});
const payload = await response.json();
console.log(payload);

Contracts and automation reference

Webhooks, signatures, retries, and replay safety