> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Global Accounts API

> Reference for 17 Global Accounts endpoints: accounts and balances, stablecoin deposits, withdrawals, account transfers, and recipients.

Version: v1.0 (2026-09-29) · Base URL: `https://api.stablepay.co` · Prefix: `/api/v1` · HTTPS / JSON / UTF-8

## Overview and Scope

The Global Accounts API manages a merchant's multi-currency accounts and account-level money movement: account and balance queries, stablecoin deposits and withdrawals, same-merchant account transfers, recipient management, and event delivery by webhook across these resources. Every path is prefixed with /api/v1. The merchant is determined by the credentials: merchant apps omit `merchant_id`, while service-provider apps use it to target a merchant.

| Method | Path | Purpose |
| :- | :- | :- |
| GET | [`/account`](https://docs.stablepayfi.ai/en/api/global-accounts/get-account) | List all accounts and balances for the target merchant |
| GET | [`/account/{account_no}`](https://docs.stablepayfi.ai/en/api/global-accounts/get-account-account-no) | Retrieve one account and balance |
| GET | [`/pending_settlement_balance`](https://docs.stablepayfi.ai/en/api/global-accounts/get-pending-settlement-balance) | Pending settlement balances by currency |
| GET | [`/fund/deposit_address`](https://docs.stablepayfi.ai/en/api/global-accounts/get-fund-deposit-address) | Retrieve a stablecoin deposit address |
| GET | [`/fund/deposits`](https://docs.stablepayfi.ai/en/api/global-accounts/get-fund-deposits) | List stablecoin deposit records |
| GET | [`/fund/deposits/{deposit_id}`](https://docs.stablepayfi.ai/en/api/global-accounts/get-fund-deposits-deposit-id) | Retrieve one stablecoin deposit |
| POST | [`/fund/deposits/{deposit_id}/confirm`](https://docs.stablepayfi.ai/en/api/global-accounts/post-fund-deposits-deposit-id-confirm) | Add Travel Rule funding source details |
| POST | [`/fund/withdrawals`](https://docs.stablepayfi.ai/en/api/global-accounts/post-fund-withdrawals) | Create a withdrawal |
| GET | [`/fund/withdrawals/{withdrawal_id}`](https://docs.stablepayfi.ai/en/api/global-accounts/get-fund-withdrawals-withdrawal-id) | Retrieve a withdrawal |
| POST | [`/fund/account_transfers`](https://docs.stablepayfi.ai/en/api/global-accounts/post-fund-account-transfers) | Create an account transfer |
| GET | [`/fund/account_transfers/{account_transfer_id}`](https://docs.stablepayfi.ai/en/api/global-accounts/get-fund-account-transfers-account-transfer-id) | Retrieve an account transfer |
| GET | [`/recipient/requirements`](https://docs.stablepayfi.ai/en/api/global-accounts/get-recipient-requirements) | Retrieve recipient field rules |
| POST | [`/recipient`](https://docs.stablepayfi.ai/en/api/global-accounts/post-recipient) | Create a recipient |
| GET | [`/recipient`](https://docs.stablepayfi.ai/en/api/global-accounts/get-recipient) | List recipients |
| GET | [`/recipient/{recipient_id}`](https://docs.stablepayfi.ai/en/api/global-accounts/get-recipient-recipient-id) | Retrieve a recipient |
| PUT | [`/recipient/{recipient_id}`](https://docs.stablepayfi.ai/en/api/global-accounts/put-recipient-recipient-id) | Update a recipient |
| DELETE | [`/recipient/{recipient_id}`](https://docs.stablepayfi.ai/en/api/global-accounts/delete-recipient-recipient-id) | Delete a recipient |

Account query endpoints use 8-digit account numbers and return lists as object with data; other endpoints use 10-digit resource IDs. Every account-related parameter uses the 8-digit `account_no`.

## Authentication and Signing

Every request carries an API Key plus the three signing headers, following the common StablePay authentication specification.

| Header | Required | Description |
| :- | :- | :- |
| Authorization | Yes | Bearer `{api_key}` |
| `X-StablePay-Timestamp` | Yes | Unix seconds; within 5 minutes of server time |
| `X-StablePay-Nonce` | Yes | Anti-replay random string, 16 to 64 characters, unique per request |
| `X-StablePay-Signature` | Yes | HMAC-SHA256 signature, lowercase hex |

The signing payload is `{timestamp}.{nonce}.{requestBody}`. GET and DELETE have no body, so `{requestBody}` is an empty string and the payload ends with a dot; POST and PUT sign the exact raw JSON string that is sent, so never reformat or reorder fields after signing. See Pre-integration Preparation for the full algorithm and multi-language samples.

Credentials belong to an app. A merchant app maps to a single merchant and omits `merchant_id`; a service-provider app serves multiple merchants after authorization and passes `merchant_id` in the query or body of account and balance queries, fund, and recipient endpoints to target a merchant. An unauthorized or inaccessible merchant returns 403 `permission_denied`. Keep the signing secret on the server, and always regenerate the timestamp and nonce when retrying.

## Data Conventions

| Item | Convention | Example |
| :- | :- | :- |
| Resource IDs | `xxx_id` values are 10-digit strings: `merchant_id`, `deposit_id`, `withdrawal_id`, `account_transfer_id`, `recipient_id`, `event_id`, `request_id` | "9000000070" |
| Account number | `account_no`. Account query endpoints return an 8-digit string; fund endpoint examples use the 00000001 form. Always use the value actually returned and never validate against a fixed pattern | "00000001", "00000001" |
| Amount | Integer in the smallest unit of the currency; fiat and USDT/USDC all use 2 decimals | 1050 means 10.50 USD; 125000 means 1,250.00 USDC |
| Currency | Uppercase; ISO 4217 for fiat, asset code for stablecoins | USD, SGD, USDT, USDC |
| Network | ethereum, tron, solana, base, polygon, arbitrum, bsc | solana |
| Time | Unix seconds as an integer | 1718726400 |
| Ratios | Ratios are decimal strings, never floats | "0.9998" |
| Empty fields | Optional fields that do not apply are omitted | — |

List endpoints use cursor pagination: limit defaults to 20 and caps at 100, the response returns `next_cursor`, and the last page omits it. The account query endpoints are the exception: the account list returns every account at once with no pagination or filters.

Create endpoints support two idempotency mechanisms: the `Idempotency-Key` header, and the `external_xxx_id` body field, which together with `merchant_id` forms a per-merchant unique key. Reusing a key with different parameters returns 409 `idempotency_conflict`; reuse the same identifier when retrying after a timeout.

## Events

Events record state changes across all merchant resources and are delivered to the merchant webhook endpoint. The event query endpoints are not publicly available; rely on webhook payloads together with reconciliation queries.

### Event Types

| Event | Description |
| :- | :- |
| account.updated | Account information changed |
| balance.updated | Available or frozen balance changed |
| deposit.completed | Stablecoin deposit credited; data is the deposit record |
| withdrawal.processing / `payment_submitted` / completed / `bounced_back` | Withdrawal lifecycle |
| `account_transfer.completed` | Account transfer completed |

Webhook requests carry `X-StablePay-Event-Type` and `X-StablePay-Event-ID`. Failed deliveries retry up to 10 times with exponential backoff starting at 2 minutes and capping at 1024 minutes. The same event may be delivered more than once, so deduplicate by `X-StablePay-Event-ID` and confirm final state with balance and record queries. See Webhook Notifications for details.

## Balance Semantics and Data Consistency

| Field | Meaning | Directly usable | Notes |
| :- | :- | :- | :- |
| `available_amount` | Available: posted and not reserved | Yes | Usable for conversion, transfers, and withdrawals |
| `frozen_amount` | Frozen: reserved by in-flight operations or risk controls | No | Becomes available when released |
| `total_amount` | Total account balance | No | Equals `available_amount` + `frozen_amount` |

The `as_of` returned by balance endpoints is the database observation time of that request, not a data version, and consecutive requests are not guaranteed to share a snapshot. Balances changing between requests is expected; the ledger is authoritative. A transfer status of completed means the business operation finished, not that the balance posted immediately. Write endpoints are protected by `Idempotency-Key` and `external_xxx_id`.

## Errors and Status Codes

Errors use a shared envelope: an error object (type, code, message, param), plus `request_id` and timestamp. Include `request_id` when reporting an issue.

Example error response

```json theme={"system"}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "The amount must be greater than zero.",
    "param": "amount"
  },
  "request_id": "9000000099",
  "timestamp": 1718726400
}
```

| Status | Code | Meaning |
| :- | :- | :- |
| 400 | `invalid_parameter` | Missing or invalid parameter, such as a zero amount or an unsupported currency or network |
| 401 | `invalid_api_key` | API key missing, invalid, or revoked, or signature verification failed |
| 403 | `permission_denied` | The merchant has not authorized this app, or the app cannot access the target merchant |
| 404 | `resource_not_found` | The resource does not exist or belongs to another merchant |
| 409 | conflict | Business state conflict: `idempotency_conflict` and `insufficient_funds` |
| 429 | `rate_limit_exceeded` | Rate limit exceeded; back off and retry |
| 500 | `internal_error` | Platform internal error; contact support with `request_id` |
| 503 | — | Balance query service temporarily unavailable; retry with a new timestamp, nonce, and signature |

error.type is one of `api_error`, `invalid_request_error`, `authentication_error`, `permission_error`, `resource_not_found`, conflict, or `rate_limit_error`. param is returned only when a specific parameter can be identified. Always regenerate the timestamp and nonce on retry, and never blindly retry a 401.

## Handling Error Codes

| Code | Retry | Recommended action |
| :- | :- | :- |
| `invalid_parameter` | No | Fix the parameter named in param and resubmit; do not replay unchanged |
| `invalid_api_key` | No | Check the key, the trailing dot in the signing payload, and server clock skew |
| `permission_denied` | No | Service-provider apps should confirm `merchant_id` is within the authorized scope |
| `resource_not_found` | No | Verify the resource ID and merchant ownership, and that it was not deleted |
| `idempotency_conflict` | No | Same key with different parameters: reuse the original payload or use a new key |
| `insufficient_funds` | No | Check `available_amount`, then adjust the amount or top up |
| `rate_limit_exceeded` | Yes | Back off exponentially and reduce concurrency |
| `internal_error` / 503 | Yes | Retry with a new timestamp, nonce, and signature; if it persists, report with `request_id` |

When retrying a write request, keep the same idempotency identifier (`Idempotency-Key` or `external_xxx_id`) and regenerate the timestamp and nonce so one operation is never executed twice.

## Version and Change Log

| Version | Change |
| :- | :- |
| 2026-09-29 | First public version: account and balance queries, stablecoin deposits and withdrawals, account transfers, and recipients — 17 endpoints. Events are delivered by webhook; no event query endpoints are provided. |

## API Boundaries

* Account opening, renaming, and merchant administration happen in the merchant dashboard, not through this API.
* The API returns only the current merchant's own accounts and transaction data; cross-merchant queries are not available.
* Cross-merchant fund movements and platform account collection are provided by the Payouts product.
* KYB and KYC submission and review status are not handled by this API.

## Related Documentation

* [Global Accounts Product Documentation](https://docs.stablepayfi.ai/en/product/Global-Accounts.md)
* [Global Accounts API Documentation](https://docs.stablepayfi.ai/en/api/global-accounts/overview)
* [Stablecoin Exchange Product Documentation](https://docs.stablepayfi.ai/en/product/Stablecoin-Exchange.md)
* [Stablecoin Exchange API Documentation](https://docs.stablepayfi.ai/en/api/stablecoin-exchange/overview)
* [Pre-integration Preparation](https://docs.stablepayfi.ai/en/api/getting-started.md)
* [Webhook Notifications](https://docs.stablepayfi.ai/en/api/webhook-notifications.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.