Operar con la API

Toda operación empieza por preparar (prepare): BotRadix valida la acción contra el mercado, tu cuenta y los contratos, la simula y devuelve exactamente lo que hay que firmar o enviar. prepare no ejecuta nada.

El flujo#

1. POST /orders/prepare con una acción, sus datos y una clave de idempotencia.
2. Revisa la respuesta: execution.ready debe ser true.
3. Ejecuta según execution.status:

Una acción preparada caduca: 120 segundos las de trading, 180 segundos las de colateral y 300 segundos las intenciones firmadas. Si caduca, vuelve a prepararla.

Camino 1 — Intención firmada (abrir y cerrar posiciones)#

Para open_position, close_position_market y close_position_limit, la respuesta trae un mensaje EIP-712 en lugar de transacciones:

• execution.mode es signed_intent y execution.transactions está vacío.
• Los datos tipados usan el dominio BotradixDEX, versión 1, chain ID 8453, y el router del DEX como contrato verificador.
• La wallet lo firma (una firma, no una transacción) y envías la firma al relay:

curl -X POST https://app.botradix.com/api/dex/actions/relay \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0xTuWallet","intent_id":"dx_…","signature":"0x…"}'
# → {"tx_hash":"0x…","state":"submitted"}

El ejecutor de BotRadix envía entonces la transacción. Su coste de red se cobra en USDC de tu colateral del DEX y se muestra antes en execution.costs, así que la wallet no necesita ETH para estas acciones.

Camino 2 — Transacciones de la wallet#

Para el resto de acciones (colateral, cambios de TP/SL, margen aislado, cancelar y reemplazar), execution.transactions contiene una o varias transacciones:

{ "kind": "action", "from": "0xTuWallet", "to": "0x…", "data": "0x…", "value": "0x0", "deadline": 1790950518 }

En los depósitos puede ir primero una de kind: "approval" (aprobación del importe exacto del token). Fírmalas y envíalas en orden desde la misma wallet; necesitan un poco de ETH en Base para el gas.

Depósito de USDC con permit (sin gas). Cuando GET /api/dex/config indica collateral_model.approval.permit: true, añade "permit": true junto a action en un add_collateral de USDC. La respuesta trae entonces execution.mode: "permit_deposit" con typed_data EIP-2612: fírmalo con la wallet y envía {"wallet","intent_id","signature"} a POST /api/dex/actions/relay. Un ejecutor del protocolo envía el depósito y paga el gas. Sin esa marca, o para BAQ, recibes las transacciones de aprobación y depósito.

Si envías tú las transacciones, comunica el hash a POST /api/dex/actions/receipt ({"wallet","intent_id","tx_hash","state"}) para recibir sus webhooks transaction.*; si no, BotRadix solo conoce la operación cuando la indexa desde la cadena.

Camino 3 — Ejecución delegada#

POST /orders/execute envía acciones mediante un ejecutor vinculado a la clave de API (scope trade:execute; orders:manage para cancelar, reemplazar y primitivas de TP/SL). Responde 202 con delegated.command_id, delegated.tx_hash y una status_url; sigue su estado con GET /executions/{command_id}. Envía "prepare_only": true para validar sin enviar.

Acepta, entre otras, open_position, batch (de 1 a 32 acciones), open_market, create_limit, create_stop, increase, reduce, close, cancel, replace, set_tp, clear_tp, set_sl, clear_sl, invert e isolated_manage. Si la clave no tiene un ejecutor vinculado, la API responde 403 delegated_executor_binding_required.

Idempotencia#

/orders/prepare exige una clave de idempotencia, que se toma (en este orden) de la cabecera Idempotency-Key, de payload.idempotency_key o de payload.client_order_id. Debe cumplir ^[A-Za-z0-9._:-]{8,128}$.

• Las claves se asocian a wallet, acción y clave, y se recuerdan 24 horas.
• La misma clave con los mismos datos devuelve la preparación original (idempotent_replay: true).
• La misma clave con datos distintos devuelve 409 IDEMPOTENCY_KEY_CONFLICT; un client_order_id reutilizado con datos distintos devuelve 409 DUPLICATE_CLIENT_ORDER_ID.
• La petición se compara con lo que enviaste (payload, más permit en los depósitos), en todas las acciones, también open_position. Los datos se validan antes de buscar la clave, así que un reintento con el mercado desfasado o movido devuelve ese error de validación. Una preparación repetida puede haber caducado: revisa expires_at_ms.

/orders/execute lee la clave solo de payload.idempotency_key o payload.client_order_id y sigue las mismas reglas: la misma clave con los mismos datos repite la respuesta original, y con datos distintos devuelve 409 IDEMPOTENCY_KEY_CONFLICT.

Datos de open_position#

Ejemplo#

curl -X POST https://app.botradix.com/api/dex/v1/orders/prepare \
  -H "X-BotRadix-API-Key: $BOTRADIX_API_KEY" \
  -H "Idempotency-Key: mm01-2026-10-02-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "open_position",
    "payload": {
      "pair_id": 1,
      "side": "long",
      "order_type": "market",
      "margin_mode": "cross",
      "order_value_usdc": "100",
      "leverage": 5,
      "reference_price": "2500.00",
      "max_slippage_bps": 50,
      "client_order_id": "mm01-2026-10-02-0001"
    }
  }'

La respuesta contiene intent_id, los datos normalizados en payload, execution (estado, datos tipados o transacciones, simulación, costes y plazo) y expires_at_ms.

Después de ejecutar#

• GET /transactions lista tus intenciones y su estado en cadena.
• GET /native/executions/{tx_hash} indica la finalidad: PENDING, PENDING_FINALITY (menos de 8 confirmaciones), REVERTED o FINAL.
• Los webhooks avisan de cambios en órdenes, posiciones, colateral y transacciones.