Workflow guide

Reconcile balances and transactions

Use balances and transactions as treasury-facing reconciliation surfaces. Do not infer invoice truth only from raw address balances.

What to poll and why

Balances

Use for treasury availability and net withdrawable views.

Transactions

Use for a compact combined feed of invoice and withdrawal activity.

Payment addresses

Use for operational address inventories, not invoice settlement decisions.

Endpoints involved

GET/api/v1/businesses/:id/balancesx-api-keySandbox + live

List balances

Return business balances grouped by asset.

When to use it

Use before quoting withdrawals or when showing operator portfolio balances.

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

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "chain": "eth",
      "networkId": "base-mainnet",
      "token": "USDC",
      "available": "149.75",
      "withdrawable": "149.50"
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/balances" \
  -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/balances', {
  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/balances/totalx-api-keySandbox + live

Get total balances

Return total gross, reserved, and net withdrawable USD values.

When to use it

Use for top-line dashboards and treasury health checks.

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

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "openInvoiceCount": 3,
  "inFlightWithdrawalCount": 1,
  "nextOpenInvoiceExpiryAt": "2026-03-14T14:15:00.000Z"
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/balances/total" \
  -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/balances/total', {
  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/balances/by-networkx-api-keySandbox + live

Get balances by network

Return balances grouped by network and token.

When to use it

Use when payout logic or treasury UI needs network-level segmentation.

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

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "networkId": "base-mainnet",
      "chain": "eth",
      "tokens": [
        {
          "symbol": "USDC",
          "available": "149.75",
          "withdrawable": "149.50"
        }
      ]
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/balances/by-network" \
  -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/balances/by-network', {
  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/balances/historyx-api-keySandbox + live

Get balance history

Return historical balance snapshots.

When to use it

Use for analytics, audit exports, or trend charts.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
startDate	query	No	ISO start date.	-
endDate	query	No	ISO end date.	-

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "asOf": "2026-03-14T13:00:00.000Z",
      "totalBalanceUSD": 12495.22
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/balances/history" \
  -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/balances/history', {
  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/transactionsx-api-keySandbox + live

List transactions

List invoices and withdrawals in one operational feed.

When to use it

Use for recent activity feeds or compact reconciliation screens.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
type	query	No	Optional `invoice` or `withdrawal` filter.	-
status	query	No	Optional lifecycle filter.	-

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "id": "inv_123",
      "type": "invoice",
      "status": "paid",
      "token": "USDC",
      "chain": "eth",
      "networkId": "base-mainnet",
      "amount": {
        "raw": "150000000",
        "decimals": 6,
        "display": "150",
        "symbol": "USDC",
        "chain": "eth",
        "networkId": "base-mainnet"
      },
      "createdAt": "2026-03-14T12:00:00.000Z"
    }
  ],
  "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/transactions" \
  -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/transactions', {
  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/transactions/summaryx-api-keySandbox + live

Get transaction summary

Return invoice and withdrawal totals for a date range.

When to use it

Use in analytics dashboards or operational summaries.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
startDate	query	No	Optional ISO start date.	-
endDate	query	No	Optional ISO end date.	-

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "invoices": {
    "total": 31,
    "paid": 24,
    "pending": 3,
    "totalAmount": "21450.18"
  },
  "withdrawals": {
    "total": 9,
    "completed": 7,
    "pending": 1,
    "totalAmount": "18500.00"
  }
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/transactions/summary" \
  -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/transactions/summary', {
  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/payment-addressesx-api-keySandbox + live

List payment addresses

List derived payment addresses owned by the business.

When to use it

Use for reconciliation, compliance review, or indexer diagnostics.

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

Cautions

These are operational addresses. Do not infer invoice state from address balance alone.

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "data": [
    {
      "chain": "eth",
      "networkId": "base-mainnet",
      "address": "0xE5fa2F71065fD49823D33EdD84ecFD2D6245c916",
      "purpose": "invoice_or_customer_deposit"
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/payment-addresses" \
  -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-addresses', {
  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/payment-addresses/:chainx-api-keySandbox + live

List payment addresses by chain

Return payment addresses for a single chain family.

When to use it

Use when you only need one chain scope, such as BTC or SOL deposit infrastructure.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
chain	path	Yes	Chain family: `eth`, `btc`, or `sol`.	-

Common errors

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

Sample response

json

{
  "data": [
    {
      "chain": "eth",
      "networkId": "base-mainnet",
      "address": "0xE5fa2F71065fD49823D33EdD84ecFD2D6245c916",
      "purpose": "invoice_or_customer_deposit"
    }
  ]
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/payment-addresses/eth" \
  -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-addresses/eth', {
  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/activity-summaryx-api-keySandbox + live

Get live activity summary

Return open-invoice and in-flight-withdrawal counters used by the dashboard.

When to use it

Use for light-weight realtime badge counts without fetching full tables.

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

Common errors

401: Missing or invalid API key.

Sample response

json

{
  "businessId": "biz_123",
  "totalBalanceUSD": 12495.22,
  "grossOnChainUSD": 12610.41,
  "reservedFeesUSD": 115.19,
  "netWithdrawableUSD": 12495.22
}

cURL example

bash

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

Business identity reference