Skip to main content
The Bitliva Merchant API authenticates every request with your API key, sent as a bearer token in the Authorization header. There are no other credentials to manage for API calls.

​
Send your API key

Keep the key on your server. Never ship it in a mobile app or browser code, because anyone who has it can act on your wallet and your customers.

​
Create an API key

1

Sign in to the merchant dashboard

Go to merchant.bitliva.com and sign in.
2

Pick the mode

Use the Sandbox / Live switch under Environment in the sidebar. Keys belong to one mode: a sandbox key only works in the sandbox, and a live key only works on live data. Live keys are available once your business is verified.
3

Open API keys

Open API keys from the menu, or go straight to merchant.bitliva.com/api-keys.
4

Name and create the key

Enter a name that tells you where the key is used, such as Production server, then select Create key.
5

Copy the key

The new key is shown once, in a pop-up, with a Copy button. Store it in your server’s secrets right away. Bitliva keeps only a hash of it, so it cannot be shown again. If you lose it, create a new one.
Sandbox keys start with bl_test_ and live keys with bl_live_. You can have up to 10 active keys per mode.

​
View your keys

The API keys page lists the active keys for the mode you are in. Each row shows the name, the start of the key (for example bl_test_a1b2c3...), when it was created and when it was last used. Keys never show in full after you create them.

​
Rotate or revoke a key

To rotate a key without downtime:
  1. Create a new key and deploy it to your server.
  2. Check that requests work with the new key. The old key’s Last used time stops changing once nothing uses it.
  3. Select Revoke on the old key and confirm.
Revoking takes effect immediately: anything still using that key gets 401 with invalid_api_key. If a key leaks, revoke it straight away and create a new one.

​
Sandbox and live modes

Responses such as GET /me and GET /balance include a mode field so you can tell which environment you are talking to. Sandbox responses report test, and live webhook payloads report live.
  • The sandbox allows 5 customers. Beyond that you get customer_limit_reached.
  • Sandbox-only endpoints, such as the deposit simulator, return sandbox_only when called outside the sandbox.
  • Live access needs a verified business. Until then, live requests return live_not_enabled.
See Sandbox testing for the sandbox-only helper.

​
Authentication errors

​
Rate limits

If you send too many requests, the API responds with 429 and the code rate_limited. Wait the number of seconds given in the Retry-After header before you try again. For the full list of codes, see Errors and response format.