Skip to main content
Every Bitnob Enterprise API request goes to https://api.platform.bitnob.com with your key in the X-API-Key header. The rest of this page covers the conventions every endpoint shares.

​
Versioning

Pin the version with the API-Version header, or put it in the path. Both of these call the same endpoint:
Leave the version out and you get the current default. An unsupported version fails with 400:
New endpoints and new optional fields are added without a version change, so write clients that ignore fields they don’t recognize. When an endpoint or version is scheduled for removal, its responses carry a Deprecation header and a Sunset header with the date it stops working.

​
Idempotency

Send an Idempotency-Key header, a unique value you generate such as a UUID, on POST, PATCH, and DELETE requests. It’s required on these endpoints: creating wallets, addresses, transactions, policies, policy rules, KYT risk profiles, and sponsored transfers, submitting sponsored transfer signatures, signing payloads, and refilling or sponsor-broadcasting gas stations. Without it, those requests fail before anything happens:
How keys behave:
  • A key is kept for 24 hours.
  • Retrying with the same key replays the original response and adds an Idempotent-Replayed: true header.
  • Reusing a key with a different request body fails with 422 idempotency_key_conflict. Generate a fresh key for every distinct operation.
  • Only successful responses are stored, so a request that failed can be retried with the same key.
  • A key sent without authentication fails with 401.

​
Pagination

List endpoints are cursor-paginated with limit, starting_after, and ending_before. Every list returns the same envelope:
When has_more is true, the response also carries a next_cursor. Pass it as starting_after to fetch the next page. Cursors are opaque, so don’t parse or build them. Sending both starting_after and ending_before fails with 400 ambiguous_cursor.

​
Errors

Every error uses one envelope:
Branch on code, which is stable. Show message to people, but don’t parse it. param names the offending field when there is one, and some errors add a details object. The Bitnob Enterprise API’s error shape is different from the Bitnob Business API’s, so don’t share one error handler between the two.

​
Rate limits

Wallet and other non-RPC requests have a per-key allowance and a shared per-minute allowance for your organization. Their responses carry these headers: The unprefixed headers report your per-key allowance or your organization’s allowance, whichever has less remaining. Slow down before you reach the limit. Over it, the API returns 429 with a Retry-After header giving the seconds to wait. POST /rpc/{chain_network} has its own limit, so RPC calls and wallet requests don’t use each other’s budget. It is a per-second limit shared by all keys and chains in your organization, and each call in a JSON-RPC batch counts separately. RPC responses don’t carry X-RateLimit headers. An RPC 429 carries only Retry-After.

​
Amounts

Money is always a JSON string, never a number, so parse it with a decimal type rather than a float. Values come in two forms:
  • amount and fee_amount are human-readable decimals in the asset’s display unit, such as "25.5" USDC.
  • amount_raw, fee_amount_raw, and wallet balance fields are integers in the asset’s smallest unit, such as "25500000" for 25.5 USDC. asset_decimals gives the conversion.
Fees are paid in fee_asset, which on most chains is the native coin rather than the asset you sent, so read fee_asset and fee_decimals instead of assuming.

​
Request tracing

Every response carries an X-Request-Id header. Log it with your own record of the request, and quote it when you contact support.