Órdenes
El namespace orders de @getenginex/sdk-predictions coloca, lista, cancela y modifica órdenes. Todos los métodos exigen login: sin sesión, rechazan con UNAUTHENTICATED antes de cualquier request.
Mira una orden enviándose, con la Idempotency-Key y el libro cambiando en vivo, en la demo de Orderbook en vivo.
Precio, cantidad y enums
- Precio: entero en centavos. En una orden límite (el valor por defecto) el
pricees obligatorio, de 1 a 99. En una orden a mercado elpricees opcional: omitido, el SDK envía0(es lo que envía la app player); si se indica, es un entero de 0 a 99. Cantidad: entero de contratos, mayor que cero. El gateway no valida nada de esto, así que el SDK rechaza los valores fuera de las reglas conCONFIGURATION_ERROR, sin request (límite conprice: 0o sinprice,100,60.5, oquantity: 0,1.5). postOnlyyreduceOnly, cuando se indican, deben ser booleanos.sidees'yes' | 'no',directiones'buy' | 'sell',orderTypees'limit' | 'market'(por defectolimit) ytimeInForcees'gtc' | 'ioc' | 'fok'(por defectogtc). Un valor fuera de estos también rechaza antes del request: el gateway trataría unorderTypedesconocido comolimit, y una orden distinta de la pedida cuesta dinero.- En la respuesta,
statusespending,open,partial,filled,canceled,expiredorejected, en minúsculas y sin el prefijo de protobuf, igual en REST y en realtime.
Colocar una orden
// Limit order: stays in the book until it executes or is canceled
const order = await predictions.orders.place({
marketId: 'mkt-1',
side: 'yes',
direction: 'buy',
price: 60, // 60 cents per contract
quantity: 10,
})
// Market order: executes whatever is in the book right away, with no price (the SDK sends price: 0)
await predictions.orders.place({
marketId: 'mkt-1',
side: 'yes',
direction: 'buy',
orderType: 'market',
timeInForce: 'ioc',
quantity: 5,
})El tipo PlaceOrderInput es una unión discriminada por orderType: el price es obligatorio en la límite y opcional en la a mercado. Un price distinto de cero en una orden a mercado no es un tope garantizado por el SDK: quien lo interpreta es el servicio de predictions, y la app player de producción siempre envía 0. Úsalo solo si sabes lo que hace.
place devuelve la Order (el gateway responde HTTP 200). postOnly: true rechaza la orden si cruzara el spread; reduceOnly: true solo permite reducir una posición existente.
Idempotencia y reintento
place mueve dinero, así que es idempotente. La misma clave va en el header Idempotency-Key y en el campo idempotency_key del cuerpo (el gateway acepta ambos), y es la misma en el reintento que el SDK hace solo después de renovar la sesión (401). Sin options.idempotencyKey, el SDK genera una clave por llamada.
Esto protege la renovación de sesión, pero no un error de red: si la llamada falla con NETWORK_ERROR o TIMEOUT, la orden puede haber llegado o no al gateway. Para reintentar sin duplicar, genera la clave una vez por intención del jugador (un clic en "Comprar"), guárdala y pasa la misma en cada intento. Los espacios en los extremos de la clave se recortan, y el mismo texto va en el header y en el cuerpo:
const key = crypto.randomUUID() // one per click, not one per attempt
const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
async function buy() {
for (let attempt = 0; ; attempt++) {
try {
return await predictions.orders.place(input, { idempotencyKey: key }) // same key: no duplicate order
} catch (error) {
const retryable =
isEnginexError(error, 'NETWORK_ERROR') || isEnginexError(error, 'TIMEOUT') || isEnginexError(error, 'KEY_IN_USE')
if (!retryable || attempt === 3) throw error
await wait(500 * 2 ** attempt) // wait before retrying (see KEY_IN_USE below)
}
}
}El gateway guarda la clave y protege contra la repetición con dos errores, que llegan con el code (el SDK los entrega aunque vengan en el formato crudo del middleware):
KEY_IN_USE(HTTP 409): la primera llamada con esa clave aún se está procesando. Espera (con backoff, como arriba) y reintenta con la misma clave; no generes otra, o la orden puede salir dos veces.PAYLOAD_MISMATCH(HTTP 422): la misma clave se usó con otra orden (otro mercado, precio o cantidad). Cada intención distinta necesita una clave nueva. (INVALID_KEY, HTTP 400, es una clave fuera del formato aceptado.)
En un origen inseguro (http://, sin crypto.randomUUID), el SDK genera la clave con crypto.getRandomValues. Sin Web Crypto alguno, no puede generar la clave y rechaza con CONFIGURATION_ERROR: pasa tu propia idempotencyKey.
Una clave nueva es una orden nueva. Una clave vacía ('') cuenta como ausente y el SDK genera otra.
Lote
const results = await predictions.orders.placeBatch({
orders: [
{ marketId: 'mkt-1', side: 'yes', direction: 'buy', price: 60, quantity: 10 },
{ marketId: 'mkt-2', side: 'no', direction: 'buy', price: 30, quantity: 5 },
],
})
for (const result of results) {
if (result.success) console.log(result.index, result.order.id)
else console.warn(result.index, result.error.message)
}- El lote no es atómico: cada orden sale bien o falla por sí sola, y un
saldo insuficienteen la segunda no deshace la primera. El resultado viene porindex(la posición en la lista enviada), ya en orden, y los fallos no se convierten en excepción. El gateway devuelve solo el mensaje del error, así queerror.codequedaundefined. - La ruta del lote no pasa por el middleware de idempotencia del gateway: no hay header
Idempotency-Keyyoptions.idempotencyKeyse ignora. Cada orden lleva unaidempotency_keydistinta en el cuerpo: laidempotencyKeyque pases en la orden (recortada; repetida en el mismo lote esCONFIGURATION_ERROR) o una generada por el SDK, nueva en cada llamada. - Para reintentar un lote con seguridad después de un error de red, guarda las claves y reenvía las mismas en cada orden (
{ ...order, idempotencyKey: 'batch-7-a' }). Sin claves tuyas, no reintentes a ciegas: las órdenes del primer envío pueden haber entrado; revisaorders.list()antes. - En las mutations (
createPredictionsMutations,useEnginexMutations), el SDK hace esto por ti: las claves se guardan por resultado decreatePredictionsMutationsdespués de un fallo ambiguo (red, timeout, 5xx,KEY_IN_USEoVALIDATION_ERRORdespués de un 2xx) o de un éxito parcial, y se reutilizan mientras el contenido del lote sea el mismo. Un éxito total, un error no ambiguo o un lote distinto generan claves nuevas. Consulta React. - La respuesta se valida en modo
strict: debe traer los índices0..n-1una vez cada uno y laorderen cada éxito; de lo contrario la llamada rechaza conVALIDATION_ERROR. - Una lista vacía o con una orden inválida rechaza con
CONFIGURATION_ERRORantes del request: ninguna orden sale.
Listar, consultar, cancelar y modificar
const orders = await predictions.orders.list() // fixed first page of 50; no filters or pagination
const one = await predictions.orders.get({ orderId: order.id })
const canceled = await predictions.orders.cancel({ orderId: order.id }) // status 'canceled'
const amended = await predictions.orders.amend({ orderId: order.id, newPrice: 55, newQuantity: 8 })amend recibe newPrice y/o newQuantity (sin ninguno de los dos, CONFIGURATION_ERROR sin request) y devuelve la orden actualizada. El gateway lo implementa como cancelar y recolocar, así que usa la orden devuelta (el id y la posición en la cola pueden cambiar). amend no es idempotente: no envía clave, y repetirlo después de un error de red puede modificar dos veces. Revisa el estado con get antes.
Un orderId vacío, con espacio al inicio o al final, o con /, . o .. rechaza con CONFIGURATION_ERROR antes del request. Lo mismo vale para el marketId de place/placeBatch.
Errores
Decide siempre por el code, no por el estado HTTP: varios códigos de predictions llegan como HTTP 500 porque el gateway no los mapea (MARKET_NOT_FOUND, MARKET_NOT_OPEN, ORDER_NOT_FOUND, NO_LIQUIDITY).
try {
await predictions.orders.place(input, { idempotencyKey: key })
} catch (error) {
if (isEnginexError(error, 'INSUFFICIENT_BALANCE')) showDeposit()
else if (isEnginexError(error, 'NO_LIQUIDITY')) notify('No offers at this price')
else if (isEnginexError(error, 'MARKET_NOT_OPEN')) notify('Market closed')
else throw error
}Pruebas
withPredictionsRoutes() incluye las rutas de órdenes (inicia sesión en el mock antes: sin token responden 401):
placedevuelve una ordenopen(colateral reservado); conorderType: 'market'se ejecuta al instante y se convierte en posición. La misma clave de idempotencia devuelve la misma orden, sin crear otra.- Una orden a mercado sin
pricese ejecuta al último precio del lado, y elpricede la orden queda en0. placeBatchcoloca cada orden por separado: unmarketIddesconocido falla esa orden (success: false) y las demás siguen.- Un mercado desconocido da
MARKET_NOT_FOUNDy una orden desconocida,ORDER_NOT_FOUND, ambos con HTTP 500, como el gateway. Para simularNO_LIQUIDITYoINSUFFICIENT_BALANCE, sobrescribe la ruta:
import { fail } from '@getenginex/sdk/testing'
createMockFetch(
withPredictionsRoutes({
routes: { 'POST /api/v1/predictions/orders': () => fail(500, 'NO_LIQUIDITY', 'no liquidity') },
}),
)