Órdenes FX (Spot)

Los servicios FX Spot permiten cotizar y ejecutar operaciones de cambio de divisas (por ejemplo, USD/CLP). A diferencia de los servicios Optimus, usan rutas bajo /v1/ y se autentican con x-api-key y x-api-secret en las cabeceras.

El flujo FX

Una operación de cambio sigue estos pasos:

1. Cotizar — obtienes el precio vigente con GET /v1/quote.
2. Preorden (opcional) — con POST /v1/customer/preorder calculas el resultado de la operación antes de comprometerla, aplicando el spread.
3. Secuencias — con GET /v1/sequences consultas las secuencias disponibles del cliente.
4. Ingresar la orden — con PUT /v1/order/{id} cursas la operación referenciando la cotización.

Cotizar

GET /v1/quote devuelve la última cotización con precios de compra y venta.

curl "/v1/quote" \
  -H "x-api-key: TU_API_KEY" \
  -H "x-api-secret: TU_API_SECRET"

{
  "success": true,
  "response": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2022-01-01T00:00:00.000Z",
    "symbol": "USD/CLP",
    "bid": 900,
    "offer": 899,
    "lowPrice": 890,
    "highPrice": 905,
    "openPrice": 900,
    "closePrice": 804
  }
}

El id de la cotización es la referencia que usarás como quoteId al calcular la preorden e ingresar la orden. Las cotizaciones tienen vigencia corta: úsala pronto o vuelve a cotizar.

Calcular una preorden

POST /v1/customer/preorder calcula el resultado de una operación sobre una cotización, aplicando el spread, sin ejecutarla. Sirve para mostrar al cliente cuánto recibirá o pagará antes de confirmar.

{
  "quoteId": "b6ac1798-c8e4-4f66-b2f8-e1fbf63afdd1",
  "clientId": "b6ac1798-c8e4-4f66-b2f8-e1fbf63afdd1",
  "amount": 1000,
  "spread": 2,
  "side": "buy",
  "currency": "USD"
}

• side — buy o sell.
• currency — USD o CLP.
• amount — monto a operar.
• spread — margen aplicado sobre la cotización.

Consultar secuencias

GET /v1/sequences lista las secuencias del cliente, con su estado y propósito. Necesitarás la secuencia adecuada al ingresar la orden.

{
  "success": true,
  "response": {
    "sequences": [
      { "secuencia": "0", "estado": "ACT", "proposito": "INTERMEDIACION" },
      { "secuencia": "9", "estado": "BLO", "proposito": "REGAPV" }
    ]
  }
}

Ingresar la orden

PUT /v1/order/{id} cursa la operación de cambio. El {id} en la ruta es el identificador de la transferencia. En el cuerpo referencias la cotización y defines la operación.

{
  "quoteId": "b6ac1798-c8e4-4f66-b2f8-e1fbf63afdd1",
  "amount": 1000,
  "valuta": 0,
  "side": "buy",
  "currency": "USD",
  "sequence": "0"
}

• valuta — condición de liquidación; valores permitidos 0, 1 o 2.
• sequence — la secuencia del cliente obtenida en el paso anterior.

Respuestas posibles: 201 orden creada, 400 errores de validación, 403 sin permiso para operar por ese cliente, 404 cliente no encontrado.

Recomendación

Cotiza justo antes de operar, ofrece al cliente una preorden para transparentar el resultado, y cursa la orden con la misma quoteId mientras siga vigente. Si la cotización expiró, vuelve a empezar desde GET /v1/quote.

El quoteId tiene un tiempo de 5 segundos de validez por lo que conviene hacer una cotización precio justo antes de ejecutar una orden.