API de ArandixBit
Integre saldos, Spot, Convertir, depósitos, retiros y webhooks con claves firmadas por HMAC y permisos por alcance. Los socios B2B operan subcuentas de sus clientes.
- Sandbox (predeterminado)
- https://api-sandbox.arandixbit.com
- WebSocket
- wss://stream.arandixbit.com/v1/ws
Visión general
La API REST de ArandixBit usa JSON sobre HTTPS. Las rutas con alcance aceptan una clave de API firmada; la gestión de claves solo acepta la sesión web del titular.
- Comience por el sandbox
https://api-sandbox.arandixbit.com: saldo ficticio, sin dinero real ni proveedores externos. El acceso de producción es privado: aparece solo en el panel de su cuenta (Configuración → API). - No existen credenciales compartidas ni de demostración: cada desarrollador crea su propia cuenta y sus claves de API en su cuenta (Configuración → API). Nunca enviamos contraseñas ni secretos por correo o chat.
- Montos en unidades mínimas enteras con su exponente en cada respuesta (ver Unidades y precisión).
- Los mensajes de error siguen
X-LangoAccept-Language(es, pt, en, gn); el campocodees estable. - La referencia (rutas, campos y descripciones) está en inglés, como el contrato OpenAPI.
Descargas
Postman, Insomnia y otras herramientas también importan el archivo OpenAPI directamente.
Inicio rápido
Cuatro pasos para su primera solicitud firmada.
- 1
Cree una clave en la app
En Ajustes → Claves de API, con 2FA activado, elija los alcances mínimos necesarios y, si es posible, vincule las IP de su servidor. El secreto se muestra una sola vez: guárdelo en un gestor de secretos.
- 2
Sincronice el reloj
La marca de tiempo debe estar a ±10 s del reloj del servidor. Consulte
GET /v1/public/time(público) y guarde la diferencia con su reloj local.curl -sS https://api-sandbox.arandixbit.com/v1/public/time # {"server_time": 1760000000000, ...} epoch milliseconds - 3
Firme la solicitud
Concatene marca de tiempo, método, ruta con query y cuerpo crudo, y calcule HMAC-SHA256 con el secreto. El asistente
arxde Autenticación y firma lo hace por usted.Texto a firmartimestamp = 1760000000000 method = GET path = /v1/spot/orders?open=true body = (empty) prehash = 1760000000000GET/v1/spot/orders?open=true signature = hex(HMAC-SHA256(api_secret, prehash)) - 4
Haga la primera llamada
GET /v1/balancescon el alcanceaccount.read(el de toda clave nueva) devuelve los saldos por moneda y billetera.export ARX_API_KEY="arxb_..." export ARX_API_SECRET="..." source ./arx.sh arx GET '/v1/balances'
Autenticación y firma
Cada solicitud firmada lleva tres cabeceras. La firma es HMAC-SHA256, en hexadecimal, del texto marca de tiempo + MÉTODO + ruta con query + cuerpo crudo.
| Cabecera | Valor |
|---|---|
X-ARX-APIKEY | ID público de la clave (arxb_…) |
X-ARX-TIMESTAMP | Epoch en milisegundos; ventana de ±10 s respecto del reloj del servidor |
X-ARX-SIGNATURE | hex(HMAC-SHA256(secreto, timestamp + MÉTODO + ruta_con_query + cuerpo)) |
Texto a firmar
- La ruta se firma exactamente como se envía, con la query y la misma codificación.
- El cuerpo es el texto JSON exacto enviado; sin cuerpo, cadena vacía. Serialice una vez y use el mismo texto para firmar y enviar.
- El método va en mayúsculas (
GET,POST,PATCH,DELETE).
timestamp = 1760000000000
method = GET
path = /v1/spot/orders?open=true
body = (empty)
prehash = 1760000000000GET/v1/spot/orders?open=true
signature = hex(HMAC-SHA256(api_secret, prehash))Asistente de firma
Los ejemplos de cada operación usan este asistente. Lea la clave y el secreto de variables de entorno, nunca del código fuente.
# arx.sh: source this file, then: arx GET '/v1/balances'
arx() {
local method="$1" req="$2" body="${3:-}"
local ts=$(( $(date +%s) * 1000 ))
local sig=$(printf '%s' "${ts}${method}${req}${body}" \
| openssl dgst -sha256 -hmac "$ARX_API_SECRET" -hex | sed 's/^.* //')
local extra=()
[ -n "$body" ] && extra=(-H "Content-Type: application/json" --data-raw "$body")
curl -sS -X "$method" "https://api-sandbox.arandixbit.com${req}" \
-H "X-ARX-APIKEY: $ARX_API_KEY" \
-H "X-ARX-TIMESTAMP: $ts" \
-H "X-ARX-SIGNATURE: $sig" \
"${extra[@]}"
}- La misma firma no vale dos veces (anti-replay).
- IP fuera de la lista vinculada: 403. Clave sin el alcance de la ruta: 403
api_key_scope_required(details.scope). - Clave vencida: 401
api_key_expired. Cambiar la contraseña, el 2FA o una passkey revoca las claves existentes. - Una cuenta bloqueada no autentica y las cuentas del equipo nunca usan claves.
- Las rutas marcadas
session(gestión de claves) aceptan solo la sesión web, nunca una clave de API.
Alcances
Una clave nueva tiene solo account.read. Elija los alcances al crearla; agregar alcances o cambiar IP exige 2FA. Cada operación de la referencia indica el alcance que exige.
| Alcance | Permite |
|---|---|
account.read | Saldos, portafolio, límites, tarifas, historial unificado y extracto. |
spot.read | Pares, libro, negocios y sus órdenes Spot. |
spot.trade | Crear y cancelar órdenes Spot (exige KYC aprobado). |
convert.read | Pares, cotización y conversiones. |
convert.execute | Ejecutar y cancelar conversiones. |
wallet.read | Depósitos (incluye crear orden de depósito USDT), retiros, lista blanca y cotizaciones de retiro. |
wallet.withdraw | Crear retiros cripto. Exige IP vinculada y solo envía a direcciones de la lista blanca con el plazo de seguridad cumplido. |
webhooks | Gestionar endpoints de webhook. |
partner.* | API B2B, solo para cuentas de socio aprobadas. |
- Hasta 30 claves por cuenta y 20 IP (IPv4 o IPv6) por clave.
- Sin IP vinculada la clave vence en 90 días; se renueva por 90 días más a partir de 5 días antes del vencimiento.
- Con IP vinculada la clave no vence.
Límites de uso
- Por clave: 600 solicitudes por minuto (valor por defecto).
- Toda respuesta autenticada por clave trae
X-RateLimit-Limit,X-RateLimit-RemainingyX-RateLimit-Reset(epoch en segundos). - Al superar el límite: 429
rate_limitedconRetry-After. Espere ese tiempo antes de reintentar. - Las rutas públicas (
/v1/public/…) tienen límite por IP; los límites del WebSocket están en su sección.
Errores
Toda respuesta de error tiene la forma {"error": {"code", "message", "details"}}. Decida por code, nunca por el texto de message, que se traduce según el idioma pedido.
{
"error": {
"code": "api_key_scope_required",
"message": "...",
"details": { "scope": "spot.trade" }
}
}| code | HTTP | Significado |
|---|---|---|
address_cooldown | 422 | The withdrawal address is still in its security cooldown after being whitelisted. |
address_not_whitelisted | 422 | The withdrawal address is not on the whitelist (required for API-key and partner withdrawals). |
api_key_customer_limit | 409 | A sub-account already has the maximum of 5 restricted keys. |
api_key_customer_restricted | 403 | A key restricted to a sub-account cannot access this route. |
api_key_customer_scope | 400 | A sub-account restricted key only accepts customer scopes (no partner.*). |
api_key_expired | 401 | The API key expired. Also returned as 409 when trying to edit or renew an expired key. |
api_key_limit | 409 | The account already has the maximum number of active API keys (30). |
api_key_no_expiry | 409 | Keys with an IP allow-list do not expire and cannot be renewed. |
api_key_renew_too_early | 409 | Renewal opens 5 days before expiry (details.renewable_from). |
api_key_required | 403 | This partner operation moves money and must be called with an API key, not a session. |
api_key_scope_required | 403 | The API key lacks the scope required by the route (details.scope). |
bad_request | 400 | Malformed JSON or invalid parameters; details maps each invalid field to a hint. |
below_min_withdrawal | 422 | Amount below the minimum withdrawal (details.min). |
conflict | 409 | The resource is not in a state that allows the operation (for example, the order is not open). |
convert_below_min_receive | 409 | The conversion would deliver less than min_receive; nothing was executed. |
convert_below_minimum | 422 | Amount below the minimum for this conversion. |
convert_limit_exceeded | 422 | Plan Convert limit (per conversion, daily or monthly) exceeded; details has window, limit_usd_minor, remaining_usd_minor. |
convert_not_filled | 409 | The external leg of the conversion was not filled; nothing was executed. |
convert_pair_in_integration | 422 | Conversions with this currency (PYG) are switched off at the moment. |
convert_pair_unavailable | 422 | This conversion pair is not available. |
customer_exists | 409 | A sub-account with this email or external reference already exists. |
deposit_limit_exceeded | 409 | Plan deposit limit exceeded (fiat deposits); details has window, level, plan, limit_usd_minor, used_usd_minor, remaining_usd_minor, amount_usd_minor. |
dubaicash_provider_unavailable | 502 | The payment provider is unavailable; nothing was charged — retry later. |
duplicate_client_order_id | 409 | Another order of the account already uses this client_order_id. |
feature_unavailable | 503 | The feature is not available in this environment. |
forbidden | 403 | Not allowed: IP not in the key allow-list, inactive account or missing permission. |
four_eyes_required | 403 | Staff: four-eyes rule — the proposer cannot approve and nobody decides on their own account. |
house_liquidity_unavailable | 503 | House liquidity for this conversion is temporarily unavailable. |
idempotency_conflict | 409 | Permanent-mode idempotency (Convert, withdrawals): the key was already used with different data. |
idempotency_key_invalid | 400 | Malformed Idempotency-Key (1–100 characters [A-Za-z0-9_.:-]). |
idempotency_key_reused | 409 | Stored-response idempotency: the key was already used for a different request (method, path or body). |
idempotency_request_in_progress | 409 | A request with the same Idempotency-Key is still executing; retry shortly. |
insufficient_funds | 422 | Not enough available balance for the operation. |
internal | 500 | Unexpected server error. Safe to retry with backoff; include X-Request-Id when contacting support. |
invalid_address | 400 | The destination address is invalid for the network. |
ip_required_for_withdraw | 400 | Keys with a withdrawal scope require an IP allow-list. |
jurisdiction_blocked | 451 | The country or jurisdiction is not served. |
kyc_already_approved | 409 | The sub-account KYC is already approved. |
kyc_disabled | 503 | Identity verification is temporarily unavailable. |
kyc_provider_error | 502 | The KYC provider could not start the verification; retry later. |
kyc_required | 403 | Approved identity verification (KYC) is required for this operation. |
limit_exceeded | 422 | Plan withdrawal limit (per transaction, daily or monthly) exceeded. |
market_unavailable | 503 | The reference market-data feed is temporarily unavailable. |
method_unavailable | 422 | The deposit method is not available for this currency. |
mexc_provider_unavailable | 502 | Pool ArandixBit is unavailable right now; retry later. |
mexc_withdraw_unavailable | 503 | Crypto withdrawals via the Pool ArandixBit are not available right now. |
mxn_amount_out_of_range | 422 | MXN deposit amount outside the allowed range. |
mxn_provider_unavailable | 502 | The MXN deposit provider is unavailable; retry later. |
mxn_too_many_open | 429 | Too many open MXN deposit charges; pay or wait for the current ones. |
no_live_price | 503 | No live price available to validate a conditional order; retry shortly. |
not_found | 404 | Resource not found (also returned for resources of other accounts). |
not_pending | 409 | The conversion was already decided and can no longer be cancelled. |
partner_grant_closed | 409 | Staff: the partner proposal was already decided. |
partner_grant_open | 409 | Staff: there is already an open proposal or the account is already a partner. |
partner_not_eligible | 422 | Staff: the account is not eligible to become a partner (business account with approved KYB required). |
partner_required | 403 | partner.* scopes and routes are only for approved partner accounts. |
payload_too_large | 413 | The request body is too large. |
pix_outside_hours | 422 | Fee-group account: PIX deposits/withdrawals are closed right now (details.kind deposit|withdrawal, start, end HH:MM, tz, days 0 = Sunday). |
pix_amount_out_of_range | 422 | PIX deposit amount outside the allowed range (details.min, details.max, BRL cents). |
pix_provider_unavailable | 502 | The PIX provider is unavailable; nothing was charged — retry later. |
pix_qr_invalid | 502 | The provider returned an invalid PIX QR code (BR Code failed CRC/format/amount checks); the deposit was closed and nothing can be paid — create a new charge or deposit USDT. |
pix_too_many_open | 429 | Too many open PIX charges; pay or wait for the current ones to expire. |
price_unavailable | 503 | No reliable live price right now (the operation fails closed); retry shortly. |
quote_expired | 409 | The Convert quote expired; request a new quote. |
quote_invalid | 400 | Unknown quote id, or a quote of another account. |
quote_mismatch | 400 | The quote does not match this request (currencies, network or amount). |
rail_disabled | 503 | This rail (Convert, USDT or withdrawal provider) is not available in this environment. |
rate_limited | 429 | Rate limit exceeded; wait Retry-After seconds. |
routing_unavailable | 503 | Liquidity routing is temporarily unavailable (502 when the external venue failed); retry later. |
sandbox_faucet_limit | 429 | Sandbox only — the daily fictitious-balance limit for this currency was reached (details.limit, details.used_minor). |
security_lock | 403 | Withdrawals are blocked for 24 h after a password or 2FA change (details.until). |
self_operation | 403 | Staff: operations on one's own account are not allowed. |
settlement_pending | 202 | The market order executed externally; internal settlement is being reconciled and the balance will be adjusted. |
staff_api_keys_forbidden | 403 | Staff accounts never use API keys (keys of promoted accounts are revoked). |
temporarily_unavailable | 503 | A dependency is temporarily unavailable; retry shortly (with the same Idempotency-Key). |
timestamp_out_of_window | 401 | X-ARX-TIMESTAMP is more than 10 s away from the server clock; details.server_time (epoch ms) and details.recv_window_ms. |
too_many_conditional | 409 | Too many open conditional orders on the account. |
totp_required | 401 | A valid 2FA (TOTP) code is required or the code is wrong. |
totp_required_for_api_keys | 403 | Enable 2FA on the account before creating API keys. |
unauthorized | 401 | Missing or invalid credentials: token, key, signature, or a replayed request. |
usdt_amount_out_of_range | 422 | USDT deposit amount outside the allowed range (details.min, details.max). |
usdt_order_failed | 502 | The USDT deposit order could not be created at the provider; retry shortly. |
usdt_too_many_open | 409 | Too many open USDT deposit orders; complete or wait for the current ones. |
usdt_unavailable | 503 | USDT deposits and withdrawals are not available right now. |
webhook_limit | 409 | Maximum number of webhook endpoints reached (10; 25 for partners). |
webhook_url_blocked | 400 | The webhook URL resolves to an internal or reserved address. |
webhook_url_invalid | 400 | Invalid webhook URL: use https, port 443 or 8443, with a public hostname. |
websocket_required | 426 | Use a WebSocket connection (RFC 6455). |
withdraw_fee_changed | 409 | The current withdrawal fee is higher than the accepted fee (max_fee or quote); nothing was debited (details.fee). |
withdraw_fee_unavailable | 503 | The network fee is unavailable right now; retry shortly. |
withdraw_quote_required | 400 | Quote the withdrawal fee (quote_id) or send max_fee before confirming. |
withdrawal_below_minimum | 422 | Fee-group account: PIX withdrawal below the group minimum (details.min_amount_minor, BRL cents). |
withdrawal_unavailable | 422 | Withdrawals on this network/asset are temporarily unavailable. |
ws_capacity | 503 | The WebSocket service is at capacity; retry shortly. |
earn_below_min_claim | 422 | Released yield is below the minimum withdrawal (US$ 100 equivalent). |
earn_below_minimum | 422 | Amount below the Earn product minimum. |
earn_matured | 409 | The position already matured; payment is automatic. |
earn_not_active | 409 | The Earn position is not active. |
earn_nothing_to_claim | 409 | No released yield to withdraw yet. |
earn_product_unavailable | 422 | The Earn product does not exist or was discontinued. |
idempotency_key_required | 400 | This route requires the Idempotency-Key header. |
Idempotencia
Los POST que cambian estado (órdenes, conversiones, retiros y demás) aceptan la cabecera Idempotency-Key. Con ella, un reintento tras un corte de red o un tiempo agotado no ejecuta la operación dos veces.
- Use un valor nuevo por operación lógica (un UUID v4, por ejemplo), de 1 a 100 caracteres
[A-Za-z0-9_-:.], y repítalo solo en los reintentos de esa misma operación. Formato inválido: 400idempotency_key_invalid. - La clave vale por cuenta y la respuesta (2xx o 4xx) se conserva durante 24 h.
- Misma clave y misma solicitud (método, ruta y cuerpo): se devuelve la respuesta guardada, sin ejecutar de nuevo, con la cabecera
Idempotent-Replayed: true. - Misma clave con otra solicitud: 409
idempotency_key_reused. Si la primera todavía se está procesando: 409idempotency_request_in_progress; reintente tras una breve espera. - Las respuestas 5xx y 429 no se guardan: puede reintentar con la misma clave.
- Convertir y los retiros deduplican la clave de forma permanente: devuelven la misma conversión o el mismo retiro; con otros datos, 409
idempotency_conflict. - Órdenes Spot:
client_order_id(1 a 36 caracteres, letras, números,-y_) identifica la orden con su propio código, único por cuenta (repetido: 409duplicate_client_order_id), y permite consultarla con?client_order_id=.
Paginación
Los listados largos usan paginación por cursor.
- Envíe
limit(el máximo de cada ruta está en la referencia) y, desde la segunda página,cursorcon el valornext_cursorde la respuesta anterior. next_cursorennullindica que no hay más páginas.- El cursor es opaco: no lo construya ni lo interprete; puede cambiar de formato sin aviso.
- El extracto en CSV (
format=csv) devuelve el cursor en la cabeceraX-Next-Cursor.
Unidades y precisión
Todos los montos son enteros en la unidad mínima de cada moneda, para evitar errores de redondeo de punto flotante.
- Cada respuesta trae el exponente:
exponenten saldos y movimientos,base_expyquote_expen pares Spot. Valor = monto ÷ 10^exponente. - Ejemplo: USDT tiene exponente 6, así que 12,5 USDT se envía como
12500000. - En Spot,
pricees la cantidad de unidades mínimas de la moneda cotizada por 1 unidad entera de la base;amountestá en unidades mínimas de la base. - Use enteros de 64 bits; en JavaScript,
BigIntpara valores que superenNumber.MAX_SAFE_INTEGER. - Fechas en RFC 3339 (UTC); marcas de tiempo de cabeceras y del WebSocket en epoch.
Versiones y cambios
La versión mayor va en la ruta (/v1). El contrato tiene una versión fechada que acompaña cada publicación.
- Dentro de
/v1solo se hacen cambios compatibles: nuevas rutas, campos opcionales, valores de enum y tipos de evento. Su integración debe ignorar campos desconocidos y tolerar valores nuevos. - Un cambio incompatible llegaría en una nueva versión de ruta, con aviso previo y período de convivencia.
- Los campos obsoletos se marcan como deprecated en la referencia antes de retirarse.
- Los eventos de webhook informan
api_version.
Registro de cambios
- Unique deposit address per invoice
- New routes
POST /v1/partner/customers/{cid}/invoice-addressesandGET /v1/partner/customers/{cid}/invoice-addresses/{id}: a new deposit address for each invoice reference of a sub-account, idempotent per reference. - Accepted:
BTC/BTC,USDT/TRC20, andUSDTorUSDConBEP20,ERC20,POLYGONandSOL. Requires scopepartner.wallet.write(restricted key:wallet.write). - Deposits to the address are credited to the sub-account like the fixed address and the
deposit.creditedwebhook carriesinvoice_address_idandreference. Another supported coin of the same network sent there is credited in the coin that arrived: compare coin and amount with the invoice.
- New routes
- Guarani buy and sell prices
- New public route
GET /v1/public/local-quoteswithbidandaskof USDT/PYG, BRL/PYG and USDT/BRL. - Conversions and Paraguay payouts with PYG use the exchange-house buying price when PYG is received and the selling price when PYG is given.
- New public route
- Manual PIX by API
- New route
POST /v1/pix/deposits/{id}/proof: API keys can send the payment proof of a manual PIX deposit. - New route
POST /v1/partner/customers/{cid}/pix/deposits/{id}/prooffor a sub-account. - While the manual flow is active, sub-account PIX deposits (
pix/depositsandfiat/deposits) answer503 pix_provider_unavailableand create nothing, unless the request sendsaccept_manual: true.
- New route
- Fixed addresses for many accounts
- With an API key,
GET /v1/crypto/fixed-address,GET /v1/partner/customers/{cid}/fixed-addressand the sub-accountpix/depositsandfiat/depositscreation routes count against the key quota only, not a limit of 20 requests per minute per IP. - A network with no address left for a new account now answers
503 crypto_deposit_network_fullinstead of502, and showspool_full: trueinmexc_deposit.networks. The Lightning network is no longer listed: it never issued a deposit address. - BRL deposits by PIX now document both flows, told apart by the
autofield: automatic charge and manual confirmation. Both go from R$ 10,00 to R$ 500.000,00 per PIX, are valid for up to 24 hours and allow up to 5 open charges and R$ 5.000.000,00 per day.
- With an API key,
- Partner Earn
- New scopes
partner.earn.readandpartner.earn.write. - New routes:
GET /v1/partner/earn/productsand/v1/partner/customers/{cid}/earn/positions(open, list, get, cancel-preview, cancel, claim). - New webhooks for sub-accounts:
earn.opened,earn.released,earn.claimed,earn.cancelled,earn.refunded,earn.matured.
- New scopes
- Partner PIX withdrawals, Paraguay payouts and fee groups
- New sub-account routes:
POST/GET /v1/partner/customers/{cid}/pix/withdrawals(+/{id}) for BRL PIX withdrawals;GET …/{cid}/py/payouts/quote,POST/GET …/{cid}/py/payouts(+/{id}) for "Receive in Paraguay" payouts;GET …/{cid}/feesfor the effective fees. - Fee groups (contract pricing):
GET /v1/me/feesaddsfee_groupwith the PIX, Convert (fractional bps,*_cbps), crypto and payout rates that replace the plan for accounts in a group; Convert quotes addfee_cbps,fee_pctandfee_group. New errors422 pix_outside_hoursand422 withdrawal_below_minimum. - Webhooks: sub-account events carry
customer_external_ref;deposit.creditedaddscredited_amountandfee(fiat and fixed-address rails); fiatwithdrawal.*addfee,netandpayment_ref, and a cancelled fiat withdrawal emitswithdrawal.failed; Paraguay payouts emitwithdrawal.sent/completed/failedwithrail: py_payout(amount,fee,net,deliver_amount). - Fiat/PIX deposits (
/v1/pix/deposits,/v1/fiat/depositsand the sub-account variants) addfeeandnet_amount(pluscredited_amountonce credited).
- New sub-account routes:
- Sandbox in sync with production
- The sandbox now runs the same code as production (more deposit coins, new fees and Convert rules), keeping its fictitious balances, simulated withdrawals and test webhook receiver.
- Fixed the
serversand WebSocketserversdescriptions of this reference, which some OpenAPI tools read as extra fields. - BRL deposits by PIX are documented with the current manual-confirmation flow (receiving account,
reference, payment proof in the app, minimum R$ 100, 5-hour validity, 0,10% fee); examples use the current rails. Identifiers of older records (dubaicashrail/processor values and error code) are unchanged for compatibility.
- More deposit coins
- Minimum deposit of US$ 10 (equivalent) on any coin: shown as
mexc_deposit.min_usd, per network asmin_amountand with the fixed address asmin_usd; a confirmed deposit below it is not credited (status: below_min). - Fixed-address deposits now cover 20+ coins.
GET /v1/rails/config→mexc_deposit.networkslists only coins the exchange holds and networks open for deposit right now, withcoin_name,confirmationsandmemo_required.
- Minimum deposit of US$ 10 (equivalent) on any coin: shown as
- Sandbox: withdrawals, Convert and webhook receiver
- Sandbox withdrawals (
POST /v1/mexc/withdrawals) now run end to end against a simulated provider, with test addresses for failure, rejection and manual review. - Sandbox Convert settles against fictitious house liquidity.
- New sandbox webhook receiver:
POST/GET /v1/sandbox/webhook-inboxes,PATCH/DELETE /v1/sandbox/webhook-inboxes/{id},GET /v1/sandbox/webhook-inboxes/{id}/requestsand the publicPOST /v1/sandbox/webhook-inboxes/receive/{token}.
- Sandbox withdrawals (
- Sandbox environment (default)
- New sandbox at
https://api-sandbox.arandixbit.com— the only server published in this reference. Fictitious balances, no real money, no external providers. Production access (endpoint and keys) is private, inside the account dashboard. - No shared or demo credentials: each developer creates their own account and API keys. New sandbox-only operations:
GET /v1/sandbox/status,POST /v1/sandbox/kyc/approve,POST /v1/sandbox/partner/activate,POST /v1/sandbox/faucetand, for partners,POST /v1/partner/customers/{cid}/sandbox/kyc/approveand/sandbox/faucet(429 sandbox_faucet_limit). All answer404in production. - Code samples read the base URL and secrets from environment variables (
ARX_API,ARX_KEY_ID,ARX_SECRET).
- New sandbox at
- Fixed deposit addresses
- New
GET /v1/crypto/fixed-addressandGET /v1/crypto/fixed-deposits: one fixed deposit address per account, coin and network; deposits are credited automatically once per transaction (deposit.creditedwithrail: "mexc",txid,address). - Partners:
GET /v1/partner/customers/{cid}/fixed-addressand/fixed-deposits(one fixed address per sub-account); sub-account crypto withdrawals viaGET …/{cid}/mexc/withdrawals/quoteandPOST …/{cid}/mexc/withdrawals(USDT included). /v1/rails/configaddsmexc_depositandusdt.deposit_paused. USDT withdrawals move toPOST /v1/mexc/withdrawals(coin: "USDT"); the legacy USDT order rail is paused (503 usdt_deposit_paused,503 usdt_withdraw_moved).
- New
- Close sub-accounts
- New
GET /v1/partner/customers/{cid}/close(closure checklist) andPOST /v1/partner/customers/{cid}/close(unlink an end customer: zero balance and nothing open required; the sub-account moves topending_closureand stops operating).
- New
- Developer experience upgrade
- New
GET /v1/public/timeserver-time endpoint for clock synchronization of signed requests. Idempotency-Keyheader on state-changing POSTs: stored-response mode (24 h replay withIdempotent-Replayed: true,idempotency_key_reused,idempotency_request_in_progress) and the existing permanent mode on Convert and withdrawals (now also sendsIdempotent-Replayed). Keys of 1–100 characters.- Spot
client_order_id(unique per account): set it onPOST /v1/spot/orders, filterGET /v1/spot/orders?client_order_id=and cancel withPOST /v1/spot/orders/by-client-id/{client_order_id}/cancel; returned on every order. 401 timestamp_out_of_windownow includesdetails.server_timeanddetails.recv_window_ms.- Reference rewritten in English with examples for every operation and the
x-arx-error-codescatalogue. - WebSocket market stream available at
wss://stream.arandixbit.com/v1/ws, backed by new public endpoints/v1/public/symbols,/v1/public/bookand/v1/public/trades. - Sub-account restricted API keys (
customer_id) for partners, withx-arx-restricted-scopeon sub-account routes. - Stable webhook delivery
error_codeon attempts, deliveries, tests and endpoints (last_error_code). - Automatic PIX reversals and MED (
deposit.reversed,withdrawal.returned, statementtype=reversal) and plan deposit limits (409 deposit_limit_exceeded,depositblock inGET /v1/me/limits). - CORS:
Idempotency-Keyaccepted;Idempotent-Replayed,X-Request-Idand rate-limit headers exposed.
- New
- Official channel verification
- New
GET /v1/public/verifyto check whether a website, email or phone number is an official channel.
- New
- Real spot fees
/v1/spot/symbolsand/v1/public/symbolsreport the maker/taker fees actually charged (fee configuration, 1 %) instead of legacy constants.
- Webhook error codes
- Stable
error_codenext to the free-text delivery error (dns_unresolved,blocked_address,connect_timeout,tls_error,http_status,redirect_not_allowed,body_too_large,secret_unavailable,invalid_url,other). PATCH /v1/webhooks/endpoints/{id}re-validates DNS only when the URL changes.
- Stable
- Public spot market data
GET /v1/public/symbols,/v1/public/book(depth 5/10/20) and/v1/public/trades(1–40) without authentication, cached for 1 s and limited per IP.
- Plan deposit limits and PIX reversals
- Plan deposit limits enforced on fiat deposit creation (
409 deposit_limit_exceeded); usage shown inGET /v1/me/limits. - Automatic PIX refunds, reversals and MED in the ledger with the
deposit.reversedandwithdrawal.returnedwebhooks.
- Plan deposit limits enforced on fiat deposit creation (
- Sub-account isolation for partners
- API keys restricted to a single sub-account (
customer_id), acting as the sub-account; automatic revocation when unlinked. - Ledger statement:
GET /v1/statementandGET /v1/partner/customers/{cid}/statement(JSON or CSV). - PIX deposits through the API:
/v1/pix/depositsand the sub-account variants, with credit only to the account in context. - Sub-accounts can register their own webhook endpoints.
- API keys restricted to a single sub-account (
- Security hardening (penetration test)
- Keys of accounts promoted to staff are rejected (
403 staff_api_keys_forbidden) and revoked. - Anti-replay of signatures persisted across instances for state-changing requests.
- Withdrawals:
Idempotency-Key(retry returns the same withdrawal) andmax_feefee cap. - Cancelling withdrawals requires
wallet.withdraw; webhook tests limited to 5 per minute; WebSocket frame limits include control frames.
- Keys of accounts promoted to staff are rejected (
- Public API launch
- Scoped API keys signed with HMAC-SHA256, IP allow-lists, expiry and per-key rate limits.
- OpenAPI 3.1 contract verified against the server routes, with localized errors (es, pt, en, gn).
- Webhooks with signed deliveries, transactional outbox, retries for about 24 hours and delivery logs.
- Public market-data WebSocket.
- B2B partner API: sub-accounts, Sumsub KYC tokens, deposits, Convert and whitelisted withdrawals.
- Unified history (
GET /v1/history) with cursor pagination.
WebSocket de mercado
wss://stream.arandixbit.com/v1/ws, sin autenticación. Canales: ticker.<SYM>, book.<SYM>[@N] (N = 5, 10, 20 o 50) y trades.<SYM>, con <SYM> = BTC-USDT. Envíe {"op":"ping"} cada 25–30 s.
- Cliente (JSON de hasta 4 KiB):
{"op":"subscribe","channels":[…]},{"op":"unsubscribe","channels":[…]}y{"op":"ping"}. - Servidor:
subscribed/unsubscribed,pong,errorconcode, y{"channel","type":"snapshot"|"update","ts","data"}. - Cada canal nuevo recibe primero una foto (
snapshot) y luego actualizaciones cada 1–2 s. - Límites: 10 conexiones por IP, 50 suscripciones por conexión y 100 mensajes cada 10 s.
- El servidor envía ping cada 25 s y cierra tras 60 s sin tramas del cliente; un cliente lento se desconecta (1008).
const ws = new WebSocket('wss://stream.arandixbit.com/v1/ws');
ws.onopen = () => {
ws.send(JSON.stringify({ op: 'subscribe', channels: ['ticker.BTC-USDT', 'book.BTC-USDT@20', 'trades.BTC-USDT'] }));
setInterval(() => ws.send(JSON.stringify({ op: 'ping' })), 25_000);
};
ws.onmessage = (m) => {
const msg = JSON.parse(m.data);
if (msg.channel) console.log(msg.channel, msg.type, msg.data);
};Webhooks
Configure endpoints en Ajustes → Webhooks o por API con el alcance webhooks. Cada entrega es un POST JSON firmado.
- Cabecera
X-ARX-Signature: t=<unix>,v1=<hex>, conv1 = HMAC-SHA256(secreto_del_endpoint, "<t>." + cuerpo_crudo). - Compare en tiempo constante y rechace
tcon más de 5 minutos. - Deduplique por
X-ARX-Event-Id(es el mismo en reintentos y reenvíos). - Responda 2xx en hasta 10 s. Reintentos exponenciales durante unas 24 h (11 intentos). No se siguen redirecciones.
- Tras 50 fallas seguidas el endpoint se desactiva y el titular recibe un correo.
- URL solo
https, puerto 443 y nombre de dominio público (no se aceptan direcciones IP); las direcciones internas o reservadas se bloquean.
Verificar la firma
import crypto from 'node:crypto';
// rawBody: the raw request body (string), before any JSON.parse
export function verifyWebhook(rawBody, signatureHeader, endpointSecret) {
const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
const expected = crypto.createHmac('sha256', endpointSecret)
.update(parts.t + '.' + rawBody)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && expected.length === parts.v1?.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}Eventos
Abra un evento para ver los campos y un ejemplo del cuerpo.
deposit.creditedDepósito acreditado (USDT, on-chain o moneda local).
deposit.reversedDepósito PIX revertido (devolución o MED).
withdrawal.sentRetiro enviado al proveedor o a la red.
withdrawal.completedRetiro completado (con txid cuando existe).
withdrawal.failedRetiro fallido, rechazado o devuelto (monto liberado).
withdrawal.returnedRetiro PIX devuelto por el banco de destino.
order.filledOrden Spot ejecutada por completo.
convert.completedConversión completada (completed o partial).
convert.pending_approvalConversión con moneda local esperando aprobación del equipo.
convert.rejectedConversión rechazada por el equipo.
kyc.status_changedCambió el estado del KYC.
partner.customer.createdSocio: subcuenta creada.
partner.customer.kyc_approvedSocio: KYC de subcuenta aprobado.
partner.customer.kyc_rejectedSocio: KYC de subcuenta rechazado.
earn.openedPartner: Earn position opened
earn.releasedPartner: Earn yield released
earn.claimedPartner: Earn yield paid
earn.cancelledPartner: Earn early exit requested
earn.refundedPartner: Earn capital refunded
earn.maturedPartner: Earn position matured
API B2B y subcuentas
Las cuentas de socio aprobadas por ArandixBit operan subcuentas de sus clientes finales con los alcances partner.*.
- Subcuentas: crear (correo nuevo, nombre y país), listar y consultar. Nunca se vincula una cuenta existente.
- KYC: el socio pide un token del WebSDK de Sumsub para el cliente final; el socio nunca aprueba identidades.
- Billetera, historial, depósito USDT, lista blanca, retiro USDT y Convertir por subcuenta, en
/v1/partner/customers/{cid}/…. - Clave restringida: con
customer_idal crear la clave, esta actúa como la subcuenta indicada, solo con alcances de cliente (hasta 5 por subcuenta). - Webhooks con
include_customersreciben también los eventos de las subcuentas (concustomer_id).
Referencia de la API
Todas las operaciones públicas del contrato, agrupadas por sección. Abra una operación para ver parámetros, cuerpo, respuestas y ejemplos de código.
MercadoMarket
Public market data, server time and the market-data WebSocket. No authentication.
CuentaAccount
Balances, portfolio, plan limits, fees, unified history and ledger statement (account.read).
Spot
Spot trading on the ArandixBit order book (spot.read / spot.trade). Trading requires approved KYC.
ConvertirConvert
Instant conversions between crypto and fiat (convert.read / convert.execute). Conversions involving fiat wait for staff approval.
BilleteraWallet
Deposits (USDT, on-chain, fiat, PIX), withdrawals (crypto, including USDT, via POST /v1/mexc/withdrawals) and the withdrawal whitelist (wallet.read / wallet.withdraw).
Webhooks
Webhook endpoints, delivery logs, test events and secret rotation (webhooks).
Gestión de clavesKeys
API key management. Interactive session only — keys cannot manage keys.
Socios B2BPartner
B2B / white-label API for approved partners: create and operate customer sub-accounts (partner.*).
Sandbox
Sandbox-only self-service: test KYC/KYB approval, B2B activation and fictitious balances. Every operation answers 404 in production.