> ## Documentation Index > Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com. > Always use the sandbox environment for testing. Never put live API keys in sample code. > Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats. > Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry. > Quotes expire. Re-quote rather than reusing a stale quote id. # Send crypto to an address > Sends BTC, USDT or USDC from your balance to an external address. reference is required and must be unique. The withdrawal starts as pending; follow it in GET /api/transactions or your webhooks. ## OpenAPI ````yaml /api-collections/swagger/bitnob-api-v2.openapi.json post /api/withdrawals openapi: 3.1.0 info: description: >- The Bitnob API for businesses: customers, virtual accounts, cards, payouts, crypto addresses and transfers, Lightning, trading and exchange rates. ## Authentication Every request is signed with your API key's client id and secret. **Signed requests (recommended).** Send: - `X-Auth-Client`: your client id - `X-Auth-Timestamp`: the current Unix time in seconds; requests more than 5 minutes off are refused - `X-Auth-Nonce`: a unique random string for this request - `X-Auth-Signature`: hex HMAC-SHA256 of `{client_id}:{timestamp}:{nonce}:{body}` using your secret, where body is the raw request body (empty for GET) **Secret mode.** Send `X-Auth-Client` and `X-Auth-Secret` instead. Simpler, but the secret travels with every request. Live keys work only for an active organisation; sandbox keys work at any time. `ANY /api/whoami` echoes the authenticated client and is the quickest way to check your signing. ## Responses Successful responses are wrapped in an envelope with `success`, `message`, `data` and, on lists, `metadata`. Errors come either as the envelope with `success: false` and an `error` object, or as an RFC 7807 problem with a machine-readable `code`; branch on the code. Every response carries an `X-Correlation-ID` header; errors repeat it as `request_id`. Quote it to support. Every request passes a per-IP rate limit of 500 requests a minute (429 with `Retry-After`). This document is maintained by hand and checked against the route table on every build: every /api route is listed here. title: Bitnob API version: 1.0.0 servers: - description: Production url: https://api.bitnob.com security: - BitnobClientId: [] BitnobClientSecret: [] tags: - description: Check that your requests are signed correctly. name: Authentication - description: >- The people and businesses you serve. Creating and editing them needs the customers feature. name: Customers - description: >- Naira accounts that receive bank transfers, for your company or for a customer. name: Virtual accounts - description: Crypto deposit addresses, for your company or for a customer. name: Addresses - description: >- Virtual cards: issue, fund, withdraw, freeze, terminate, and the card KYC and corporate onboarding behind them. name: Cards - description: 'Pay out to bank accounts and mobile money: quote, initialize, finalize.' name: Payouts - description: Saved payout recipients. name: Beneficiaries - description: Banks and account lookups for payouts. name: Banks - description: Balance transfers between Bitnob organisations. name: Transfers - description: Crypto withdrawals. name: Withdrawals - description: Lightning invoices and payments. name: Lightning - description: Lightning addresses, LNURL withdraw links and LNURL payments. name: LNURL - description: Blockchain node access. name: Nodes - description: Quotes and orders for buying and selling. name: Trading - description: Rates and conversions. name: Exchange rates - description: Your transaction history. name: Transactions - description: Wallet balances. name: Balances paths: /api/withdrawals: post: tags: - Withdrawals summary: Send crypto to an address description: >- Sends BTC, USDT or USDC from your balance to an external address. reference is required and must be unique. The withdrawal starts as pending; follow it in GET /api/transactions or your webhooks. operationId: withdrawalsCreate requestBody: content: application/json: examples: btc_bitcoin: summary: 0.0005 BTC (50000 sats) on bitcoin value: amount: '50000' chain: bitcoin currency: BTC memo: October payout reference: wd_sbx_20261030_0003 to_address: tb1qexamplesandboxaddress000000000000000000 usdc_ethereum: summary: 100 USDC on Ethereum value: amount: '100000000' chain: ethereum currency: USDC reference: wd_sbx_20261030_0002 to_address: '0x000000000000000000000000000000000000dEaD' usdt_tron: summary: 25 USDT on Tron value: amount: '25000000' chain: tron currency: USDT description: Supplier settlement reference: wd_sbx_20261030_0001 to_address: TExampleSandboxAddress000000000001 schema: $ref: '#/components/schemas/WithdrawalsCreateRequest' required: true responses: '201': content: application/json: examples: pending: summary: >- Accepted; the balance is debited and the send is broadcast in the background value: data: address: TExampleSandboxAddress000000000001 amount: '25000000' chain: tron created_at: '2026-10-30T09:15:02Z' currency: USDT description: Supplier settlement memo: '' reference: wd_sbx_20261030_0001 status: pending transaction_id: 019a3b60-7da6-75c8-9091-3c4d5e6f7a80 transfer_id: 019a3b60-7da6-75c8-9091-3c4d5e6f7a89 message: Transfer initiated successfully success: true timestamp: '2026-10-30T09:15:02.481Z' schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: $ref: '#/components/schemas/WithdrawalsWithdrawal' type: object description: Created '400': content: application/json: examples: amount_not_base_units: summary: amount has decimals value: code: VALIDATION_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: amount must be in base units (whole number, no decimals) request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 400 timestamp: '2026-10-30T09:15:02Z' title: Validation Error type: https://api.bitnob.com/errors/VALIDATION_ERROR currency_for_chain: summary: USDT on bitcoin, or BTC on another chain value: code: VALIDATION_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: invalid request extensions: field_violations: - description: invalid currency for chain field: currency - description: Bitcoin requires BTC, other chains require USDC/USDT field: chain request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 400 timestamp: '2026-10-30T09:15:02Z' title: Validation Error type: https://api.bitnob.com/errors/VALIDATION_ERROR field_validation: summary: Required fields missing or invalid value: error: code: BAD_REQUEST details: amount: Amount must be a number reference: Reference is required message: Validation failed request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 success: false timestamp: '2026-10-30T09:15:02.481Z' invalid_address: summary: to_address is not valid for the chain value: code: VALIDATION_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: invalid request extensions: field_violations: - description: invalid destination address field: to_address request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 400 timestamp: '2026-10-30T09:15:02Z' title: Validation Error type: https://api.bitnob.com/errors/VALIDATION_ERROR malformed_body: summary: The body is not valid JSON value: error: code: BAD_REQUEST message: Invalid request body request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 success: false timestamp: '2026-10-30T09:15:02.481Z' schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/Problem' description: >- The body does not parse or fails the handler's checks (BAD_REQUEST envelope), or the service refuses a field (VALIDATION_ERROR, field_violations in extensions): an amount with decimals, an unsupported currency or chain, a currency the chain does not carry, or an invalid address. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '401': $ref: '#/components/responses/Unauthorized' '403': content: application/json: examples: account_transactions_paused: summary: Money movement is frozen for this organisation value: code: FEATURE_NOT_ENABLED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- Transactions on this account are currently paused. Contact support if you did not request this. extensions: company_id: 019a3b5c-1f0e-7d2c-8a9b-4c5d6e7f8a90 feature_key: money_movement_enabled requested_feature_key: send_stablecoins request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Account Transactions Paused type: https://api.bitnob.com/errors/FEATURE_NOT_ENABLED client_inactive: $ref: '#/components/examples/ClientInactive' feature_not_enabled: summary: send_stablecoins is off for this organisation value: code: FEATURE_NOT_ENABLED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- The stablecoin withdrawals feature is currently not available. extensions: company_id: 019a3b5c-1f0e-7d2c-8a9b-4c5d6e7f8a90 feature_key: send_stablecoins request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Feature Not Enabled type: https://api.bitnob.com/errors/FEATURE_NOT_ENABLED ip_not_whitelisted: $ref: '#/components/examples/IPNotWhitelisted' org_not_active: $ref: '#/components/examples/OrgNotActive' org_not_active_live: $ref: '#/components/examples/OrgNotActiveLive' risk_refusal: summary: Refused by the risk checks value: code: FORBIDDEN correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- transfer: unable to process this request, please contact support request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Forbidden type: https://api.bitnob.com/errors/FORBIDDEN schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/Problem' description: >- FEATURE_NOT_ENABLED: the send feature for the currency is off, money movement is halted, or this organisation's transactions are paused; FORBIDDEN: the send was refused for risk reasons; ORG_NOT_ACTIVE for a live key on an inactive organisation; or a refusal before the handler. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '404': content: application/json: examples: master_address_not_found: summary: The chain is not set up to send from value: code: NOT_FOUND correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: master address not found for chain request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 404 timestamp: '2026-10-30T09:15:02Z' title: Resource Not Found type: https://api.bitnob.com/errors/NOT_FOUND schema: $ref: '#/components/schemas/Problem' description: >- NOT_FOUND: the chain has no master address configured in this environment. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '408': $ref: '#/components/responses/RequestTimeout' '409': content: application/json: examples: duplicate_reference: $ref: '#/components/examples/DuplicateKey' schema: $ref: '#/components/schemas/Problem' description: >- DUPLICATE_KEY_ERROR: a withdrawal with this reference already exists. Look it up instead of resending. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '412': content: application/json: examples: tier_limit_reached: summary: Over the daily outflow ceiling value: code: TIER_LIMIT_REACHED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- This transfer would exceed your daily crypto outflow limit of 10000 USD (used 9990, requested 25) extensions: direction: out limit: '10000' rail: crypto remaining: '10' requested: '25' tier: '1' unit: crypto used: '9990' window: daily request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 412 timestamp: '2026-10-30T09:15:02Z' title: Tier Limit Reached type: https://api.bitnob.com/errors/TIER_LIMIT_REACHED schema: $ref: '#/components/schemas/Problem' description: >- TIER_LIMIT_REACHED: the withdrawal would exceed the organisation's tier limit; the figures are in extensions. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '422': content: application/json: examples: address_blocked: summary: The address is on the blocklist value: code: PRECONDITION_FAILED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: destination address is blocked request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 422 timestamp: '2026-10-30T09:15:02Z' title: Precondition Failed type: https://api.bitnob.com/errors/PRECONDITION_FAILED address_flagged: summary: Looks like an address-poisoning lookalike value: code: PRECONDITION_FAILED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: destination address flagged for security review request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 422 timestamp: '2026-10-30T09:15:02Z' title: Precondition Failed type: https://api.bitnob.com/errors/PRECONDITION_FAILED below_minimum: summary: Below the withdrawal minimum value: code: PRECONDITION_FAILED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- transfer: withdrawal amount below minimum: minimum is $1 USD request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 422 timestamp: '2026-10-30T09:15:02Z' title: Precondition Failed type: https://api.bitnob.com/errors/PRECONDITION_FAILED chain_not_enabled: summary: The chain is switched off for this organisation value: code: PRECONDITION_FAILED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: chain is not enabled for this company request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 422 timestamp: '2026-10-30T09:15:02Z' title: Precondition Failed type: https://api.bitnob.com/errors/PRECONDITION_FAILED insufficient_funds: summary: The balance is short value: code: INSUFFICIENT_FUNDS correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: insufficient balance request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 422 timestamp: '2026-10-30T09:15:02Z' title: Insufficient Funds type: https://api.bitnob.com/errors/INSUFFICIENT_FUNDS not_whitelisted: summary: Withdrawal whitelisting is on and the address is not on it value: code: PRECONDITION_FAILED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: destination address not whitelisted request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 422 timestamp: '2026-10-30T09:15:02Z' title: Precondition Failed type: https://api.bitnob.com/errors/PRECONDITION_FAILED tron_not_activated: summary: The Tron destination has never received TRX value: code: PRECONDITION_FAILED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- transfer: Tron account is not activated - send TRX to activate it first request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 422 timestamp: '2026-10-30T09:15:02Z' title: Precondition Failed type: https://api.bitnob.com/errors/PRECONDITION_FAILED schema: $ref: '#/components/schemas/Problem' description: >- INSUFFICIENT_FUNDS: the balance does not cover amount plus network fee; PRECONDITION_FAILED: the destination is blocked, flagged or not whitelisted, the amount is outside the withdrawal limits, the chain is not enabled, or the destination account is not activated. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '429': content: application/json: examples: rate_limited: $ref: '#/components/examples/RateLimited' velocity_limit: summary: A velocity or cooldown limit; try again later value: code: RATE_LIMIT_EXCEEDED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- transfer: temporarily unable to process this request, please try again later request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 429 timestamp: '2026-10-30T09:15:02Z' title: Service Rate Limited type: https://api.bitnob.com/errors/RATE_LIMIT_EXCEEDED schema: $ref: '#/components/schemas/Problem' description: >- RATE_LIMIT_EXCEEDED: a velocity, cooldown or per-recipient limit was hit, or the per-IP limiter refused the request. headers: Retry-After: $ref: '#/components/headers/Retry-After' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' '500': $ref: '#/components/responses/ServerError' '503': content: application/json: examples: auth_service_busy: $ref: '#/components/examples/AuthServiceBusy' auth_service_unavailable: $ref: '#/components/examples/AuthServiceUnavailable' limits_unavailable: $ref: '#/components/examples/LimitsUnavailable' platform_paused: summary: Paused by a platform control value: code: PLATFORM_PAUSED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- Money movement is temporarily paused. Nothing is lost — requests can be retried once the pause lifts. extensions: requested_feature_key: send_stablecoins scope: asset:USDT request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 503 timestamp: '2026-10-30T09:15:02Z' title: Money Movement Paused type: https://api.bitnob.com/errors/PLATFORM_PAUSED partner_unavailable: $ref: '#/components/examples/PartnerUnavailable' schema: $ref: '#/components/schemas/Problem' description: >- LIMITS_UNAVAILABLE: the tier limit check could not run; PLATFORM_PAUSED: a platform control paused money movement; SERVICE_UNAVAILABLE: the ledger, price or security checks are unavailable. Retry with the same reference. headers: Retry-After: $ref: '#/components/headers/Retry-After' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' components: schemas: WithdrawalsCreateRequest: properties: amount: description: >- Positive whole number in base units of currency (satoshis for BTC, 10^-6 for USDT and USDC) pattern: ^[0-9]+$ type: string chain: description: Chain to send on, e.g. bitcoin, tron, ethereum, solana maxLength: 30 pattern: ^[A-Za-z0-9]+$ type: string currency: description: BTC, USDT or USDC; Bitcoin requires BTC, other chains USDT or USDC maxLength: 10 type: string description: maxLength: 500 type: string description: Your note for this withdrawal. memo: maxLength: 500 type: string description: Memo or destination tag, for chains that use one. reference: description: Your reference; also the idempotency key for the withdrawal maxLength: 100 type: string to_address: description: Destination address type: string required: - to_address - amount - currency - chain - reference type: object Envelope: description: >- Successful responses are wrapped in this envelope, and so are errors a handler answers itself (request body and field validation, some not-found and conflict cases, ORG_NOT_ACTIVE): success is false and error carries a code and message. Errors raised by authentication and by the services behind a handler are a Problem instead. properties: data: description: >- The payload; its shape is given per operation. Omitted when there is none. error: $ref: '#/components/schemas/ErrorInfo' message: description: Human-readable summary; omitted when empty. type: string metadata: $ref: '#/components/schemas/Pagination' request_id: description: >- Set on error envelopes: the request's correlation id (req_ followed by a UUID), the same value as the X-Correlation-ID response header. Quote it to support. type: string success: description: true on success type: boolean timestamp: description: When the response was written. format: date-time type: string required: - success - timestamp type: object WithdrawalsWithdrawal: properties: address: description: Destination address type: string amount: description: Base units type: string chain: type: string created_at: format: date-time type: string currency: type: string description: type: string memo: type: string reference: type: string status: type: string transaction_id: description: Ledger transaction id type: string transfer_id: format: uuid type: string required: - transaction_id - transfer_id - status - address - amount - currency - chain - reference - created_at - memo - description type: object ErrorEnvelope: allOf: - $ref: '#/components/schemas/Envelope' - properties: success: const: false required: - error type: object description: >- The envelope as an error: success is false, error is set, data is absent. Problem: description: >- RFC 7807 problem. Returned when authentication fails and for errors raised by the services behind a handler (validation, domain refusals such as FEATURE_NOT_ENABLED or PRECONDITION_FAILED, partner outages); branch on code. properties: code: description: >- Machine-readable; branch on this, not on the status or the wording. For example VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_NOT_ENABLED, PERSONAL_WORKSPACE_CUSTOMERS, TIER_PRODUCT_LOCKED, NOT_FOUND, DUPLICATE_KEY_ERROR, ALREADY_EXISTS, PRECONDITION_FAILED, INSUFFICIENT_FUNDS, TIER_LIMIT_REACHED, RATE_LIMIT_EXCEEDED, TIMEOUT, SERVICE_UNAVAILABLE, LIMITS_UNAVAILABLE, PLATFORM_PAUSED, INTERNAL_ERROR. type: string correlation_id: description: >- The request's correlation id, the same value as the X-Correlation-ID response header. type: string detail: description: >- What went wrong for this request, safe to show; internal and partner failures carry a generic sentence. type: string extensions: additionalProperties: true description: >- Code-specific facts, for example feature_key (FEATURE_NOT_ENABLED), field or field_violations (VALIDATION_ERROR), rail, window, limit, used, requested and remaining (TIER_LIMIT_REACHED), scope (PLATFORM_PAUSED). type: object instance: type: string request_id: description: Equal to correlation_id. type: string status: description: The HTTP status, repeated. type: integer timestamp: format: date-time type: string title: description: >- Short summary of the code, for example Validation Error or Feature Not Enabled. type: string type: description: https://api.bitnob.com/errors/{code} format: uri type: string required: - type - title - status - code - timestamp type: object ErrorInfo: properties: code: description: >- Machine-readable, for example BAD_REQUEST, NOT_FOUND, CONFLICT, ORG_NOT_ACTIVE, RATE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE, INTERNAL_ERROR. type: string details: additionalProperties: true description: >- For field validation, a map of field name to message ("email": "Email must be a valid email address"); for a body that does not decode, the offending field. type: object message: type: string required: - message type: object Pagination: description: >- List metadata. Page lists set page, per_page, total and total_pages; offset and cursor lists set limit, offset, has_more and next_cursor. Zero and empty fields are omitted, and metadata is absent when nothing is set. properties: has_more: type: boolean limit: type: integer next_cursor: description: Opaque; pass as cursor for the next page. type: string offset: type: integer page: type: integer per_page: type: integer total: type: integer total_pages: type: integer type: object headers: X-Correlation-ID: description: >- Generated for every request (any value the client sends is ignored); quote it to support. Errors repeat it as request_id and correlation_id. example: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 schema: type: string Retry-After: description: Seconds to wait before retrying. example: 1 schema: minimum: 0 type: integer responses: Unauthorized: content: application/json: examples: unauthorized_auth_failed: $ref: '#/components/examples/UnauthorizedAuthFailed' unauthorized_invalid_secret: $ref: '#/components/examples/UnauthorizedInvalidSecret' unauthorized_invalid_signature: $ref: '#/components/examples/UnauthorizedInvalidSignature' unauthorized_locked_out: $ref: '#/components/examples/UnauthorizedLockedOut' schema: $ref: '#/components/schemas/Problem' description: >- Authentication failed: a signing header is missing or malformed, the timestamp is more than 5 minutes off, the signature or secret is wrong, or the client is locked out after failed checks (UNAUTHORIZED). headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' RequestTimeout: content: application/json: examples: request_timeout: $ref: '#/components/examples/RequestTimeout' schema: $ref: '#/components/schemas/Problem' description: >- The request ran past its deadline (TIMEOUT); retry, with the same reference for writes. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' ServerError: content: application/json: examples: internal_error: $ref: '#/components/examples/InternalError' internal_error_envelope: $ref: '#/components/examples/InternalErrorEnvelope' internal_error_unhandled: $ref: '#/components/examples/InternalErrorUnhandled' schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/Problem' description: >- Something failed on our side; safe to retry idempotent requests (INTERNAL_ERROR). headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' examples: ClientInactive: summary: The API key's client is deactivated value: code: FORBIDDEN correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Client account is inactive request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Forbidden type: https://api.bitnob.com/errors/FORBIDDEN IPNotWhitelisted: summary: The request came from an IP not on the key's allowlist value: code: FORBIDDEN correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: IP address not whitelisted request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 403 timestamp: '2026-10-30T09:15:02Z' title: Forbidden type: https://api.bitnob.com/errors/FORBIDDEN OrgNotActive: description: Live keys only; sandbox requests pass. summary: A money-moving operation from an organisation that is not active value: error: code: ORG_NOT_ACTIVE message: >- Your organisation is not currently active. Please contact your administrator. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 success: false timestamp: '2026-10-30T09:15:02.481Z' OrgNotActiveLive: description: Sandbox keys are never refused this way. summary: A live key on an organisation that is not active yet value: error: code: ORG_NOT_ACTIVE message: >- Your business isn't active yet, so live isn't available. Use your sandbox keys until it's activated. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 success: false timestamp: '2026-10-30T09:15:02.481Z' DuplicateKey: summary: A resource with the same reference or identifier exists value: code: DUPLICATE_KEY_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: A resource with the same identifier already exists. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 409 timestamp: '2026-10-30T09:15:02Z' title: Resource Already Exists type: https://api.bitnob.com/errors/DUPLICATE_KEY_ERROR RateLimited: summary: The per-IP limit (500 requests a minute) is reached value: code: RATE_LIMIT_EXCEEDED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Too many requests. Please try again later. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 429 timestamp: '2026-10-30T09:15:02Z' title: Rate Limit Exceeded type: https://api.bitnob.com/errors/RATE_LIMIT_EXCEEDED AuthServiceBusy: description: 'Sent with Retry-After: 1.' summary: Too many large signed bodies are being checked at once value: code: SERVICE_UNAVAILABLE correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Authentication service is busy, retry shortly request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 503 timestamp: '2026-10-30T09:15:02Z' title: Service Unavailable type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE AuthServiceUnavailable: description: 'Sent with Retry-After: 1. The detail is worded exactly like this today.' summary: The identity service could not be reached to check the credentials value: code: SERVICE_UNAVAILABLE correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Service Authentication service unavailable is currently unavailable request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 503 timestamp: '2026-10-30T09:15:02Z' title: Service Unavailable type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE LimitsUnavailable: summary: The tier limit check could not run value: code: LIMITS_UNAVAILABLE correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: >- We could not verify your account limits right now. Please try again shortly. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 503 timestamp: '2026-10-30T09:15:02Z' title: Limits Unavailable type: https://api.bitnob.com/errors/LIMITS_UNAVAILABLE PartnerUnavailable: summary: A partner or internal service is unavailable value: code: SERVICE_UNAVAILABLE correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Service is temporarily unavailable. Please try again later. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 503 timestamp: '2026-10-30T09:15:02Z' title: Service Unavailable type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE UnauthorizedAuthFailed: description: >- Returned when X-Auth-Client, X-Auth-Timestamp, X-Auth-Nonce or X-Auth-Signature is missing, the nonce is not 8 to 128 characters, the signature is not hex, or the timestamp is more than 5 minutes from the server's clock. The detail does not say which; check each. summary: A signing header is missing or malformed, or the timestamp is stale value: code: UNAUTHORIZED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Authentication failed request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 401 timestamp: '2026-10-30T09:15:02Z' title: Unauthorized type: https://api.bitnob.com/errors/UNAUTHORIZED UnauthorizedInvalidSecret: summary: 'Secret mode: the client id or secret is wrong' value: code: UNAUTHORIZED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Invalid credentials request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 401 timestamp: '2026-10-30T09:15:02Z' title: Unauthorized type: https://api.bitnob.com/errors/UNAUTHORIZED UnauthorizedInvalidSignature: description: >- The detail is the identity service's reason when it gives one (an unknown client or a reused nonce reads differently); Invalid signature otherwise. summary: The signature does not match value: code: UNAUTHORIZED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Invalid signature request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 401 timestamp: '2026-10-30T09:15:02Z' title: Unauthorized type: https://api.bitnob.com/errors/UNAUTHORIZED UnauthorizedLockedOut: summary: Too many failed credential checks value: code: UNAUTHORIZED correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: Too many failed credential checks; retry later request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 401 timestamp: '2026-10-30T09:15:02Z' title: Unauthorized type: https://api.bitnob.com/errors/UNAUTHORIZED RequestTimeout: summary: The request ran past its deadline value: code: TIMEOUT correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: The request took too long to complete. Please try again. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 408 timestamp: '2026-10-30T09:15:02Z' title: Request Timeout type: https://api.bitnob.com/errors/TIMEOUT InternalError: summary: Something failed on our side value: code: INTERNAL_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: An internal error occurred. Please try again later. request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 500 timestamp: '2026-10-30T09:15:02Z' title: Internal Server Error type: https://api.bitnob.com/errors/INTERNAL_ERROR InternalErrorEnvelope: summary: A failure answered by the handler value: error: code: INTERNAL_ERROR message: Failed to list transactions request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 success: false timestamp: '2026-10-30T09:15:02.481Z' InternalErrorUnhandled: summary: An unexpected failure value: code: INTERNAL_ERROR correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 detail: An internal server error occurred request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091 status: 500 timestamp: '2026-10-30T09:15:02Z' title: Internal Server Error type: https://api.bitnob.com/errors/INTERNAL_ERROR securitySchemes: BitnobClientId: type: apiKey in: header name: X-Auth-Client description: | Your workspace client id. All calls must include four headers: - `X-Auth-Client` — your workspace client id - `X-Auth-Timestamp` — Unix seconds - `X-Auth-Nonce` — 16-byte random hex - `X-Auth-Signature` — hex(HMAC-SHA256( `{client_id}:{timestamp}:{nonce}:{raw_body}`, client_secret)) The playground computes the timestamp, nonce and signature for you. BitnobClientSecret: type: apiKey in: header name: X-Playground-Client-Secret description: > Your sandbox client secret. The playground uses it to sign the request in your browser and removes it before the request is sent. Never send your client secret as a header in your own integration. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.