inicio

API

Operar

Coloca, agrupa y cancela órdenes en Seeryx: órdenes límite, de mercado y solo maker, claves de idempotencia, vencimiento, división y combinación, con ejemplos.

Descripción general

Operas con POST /api/orders (una orden) o POST /api/orders/batch (hasta 15), cancelas con DELETE /api/orders/:id o DELETE /api/orders, y conviertes efectivo en pares y viceversa con /api/split y /api/merge. En seeryx.com cada orden, división y combinación lleva un objeto signed creado por tu clave de sesión de trading: Firma de órdenes explica cómo; los ejemplos de esta página lo hacen por ti.

Cabeceras e idempotencia

CampoTipoDescripción
X-Auth-TokencabeceraobligatoriostringEl token de inicio de sesión (o Authorization: Bearer).
Idempotency-KeycabeceraobligatoriostringEn cada POST y DELETE que opera: de 8 a 128 letras, dígitos, _ o -, nueva para cada acción. La misma clave con el mismo cuerpo responde lo mismo que la primera solicitud y no cambia nada; con otro cuerpo, se rechaza. Las claves se recuerdan durante 24 horas.
Content-Typecabeceraobligatoriostringapplication/json cuando hay cuerpo.

Tipos de órdenes

TipoCamposQué ocurre
Límiteshares, limitSe ejecuta al instante contra lo que se ofrece a su precio o mejor, y el resto queda en el libro hasta que se ejecute, la canceles o cierre la ronda.
Límite, solo makershares, limit, postOnly: trueQueda entera en el libro o se rechaza (400 would_take): nunca toma liquidez, así que nunca paga la comisión taker.
Compra de mercadoamount, capGasta hasta amount USDC (comisión incluida) a precios de hasta cap, al instante; el resto se descarta y nunca queda en el libro.
Venta de mercadoshares, capVende hasta shares acciones a precios que no bajen de cap, al instante; el resto se descarta.
CampoTipoDescripción
slugobligatoriostringUna ronda que se opera (en vivo o próxima) o un mercado de eventos abierto.
sideobligatorioup | downEl resultado que operas (en un mercado de eventos, SÍ es up y NO es down).
actionobligatoriobuy | sellUna venta necesita acciones que tengas y que ninguna otra venta en el libro haya reservado.
typeobligatoriolimit | marketVer arriba.
sharesopcionalnumberÓrdenes límite y todas las ventas.
amountopcionalnumberCompras de mercado: lo máximo que se gasta en USDC, comisión taker incluida.
limitopcionalnumberÓrdenes límite: el precio en centavos.
capopcionalnumberÓrdenes de mercado: el peor precio en centavos. Una compra no paga más; una venta no acepta menos.
postOnlyopcionalbooleanSolo órdenes límite.
signedopcionalobjectLa orden firmada por tu clave de sesión (Firma de órdenes).
QuieresCuerpo (más slug y signed)
Comprar 10 Sube a 45¢ o mejor, en el libro{"side":"up","action":"buy","type":"limit","shares":10,"limit":45}
Gastar ahora hasta 5 $ en Baja, como máximo a 60¢ por acción{"side":"down","action":"buy","type":"market","amount":5,"cap":60}
Vender ahora 10 Sube, por al menos 40¢{"side":"up","action":"sell","type":"market","shares":10,"cap":40}
Ofrecer 10 Sube a 70¢, solo como maker{"side":"up","action":"sell","type":"limit","shares":10,"limit":70,"postOnly":true}

La respuesta

Respuestas
{ "order": 16901, "filled": 0, "remaining": 10, "spent": 0, "proceeds": 0 }

{ "order": null, "filled": 10.6844, "remaining": 0, "spent": 4.999974, "proceeds": 0,
  "requested": 5, "fee": 0.18515, "avgPrice": 45.064056006888556, "unspent": 0.000026, "status": "filled" }

{ "order": null, "filled": 0, "remaining": 0, "spent": 0, "proceeds": 0, "requested": 5, "fee": 0, "avgPrice": null,
  "unspent": 5, "status": "none", "reason": "beyond_limit", "limit": 1, "bestPrice": 16 }
Una orden límite en el libro; una compra de mercado de 5 $ que se ejecutó; una compra de mercado cuyo cap estaba por debajo de la mejor venta.
  • order es el id de lo que queda en el libro, null cuando no queda nada. filled son las acciones operadas ahora; spent y proceeds son los USDC pagados y recibidos, comisiones incluidas.
  • Una orden de mercado añade requested, fee, avgPrice (centavos, sin la comisión), unspent o unsold, status (filled, partial o none) y, cuando no se ejecutó por completo, reason: no_liquidity, beyond_limit (con bestPrice) o share_limit.
  • Una orden de mercado que no ejecuta nada sigue siendo un 200, no un error.

Vencimiento y cierre

  • Las órdenes límite se firman hasta el cierre del mercado (el final de la ronda o el closesAt de un evento) y quedan en el libro hasta entonces.
  • Las órdenes de mercado, las divisiones y las combinaciones se liquidan en segundos, así que fírmalas por 5 minutos, nunca más allá del cierre. El servidor acepta un vencimiento desde 5 segundos en el futuro hasta el cierre.
  • En los últimos 5 segundos de una ronda no se aceptan órdenes nuevas (400 "Round is closing"). Las órdenes en el libro vencen al cierre y aparecen con el tipo expire en tu actividad.
  • Rondas por adelantado. Las diez rondas siguientes de 5m y 15m (una de 1h y de 1d) ya aceptan órdenes, así que un bot puede cotizar una ronda antes de que empiece.

Lotes y cancelaciones

POST /api/orders/batch coloca hasta 15 órdenes en una sola solicitud, en el orden indicado, cada una con sus propias comprobaciones: la respuesta tiene un { status, body } por orden, exactamente lo que habría respondido POST /api/orders. La orden i se registra con <your key>-<i>, así que reintentar el lote entero con la misma clave no coloca nada dos veces. DELETE /api/orders cancela todas tus órdenes abiertas, o con ?slug= las de un mercado, en una sola transacción.

curl
# two orders in one request (on seeryx.com each also carries its own "signed")
curl -s -X POST https://seeryx.com/api/orders/batch \
  -H "X-Auth-Token: $TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"orders":[{"slug":"btc-updown-5m-1791916200","side":"up","action":"buy","type":"limit","shares":5,"limit":40},
                 {"slug":"btc-updown-5m-1791916200","side":"down","action":"buy","type":"limit","shares":5,"limit":40}]}'
# {"results":[{"status":200,"body":{"order":21306,...}},{"status":200,"body":{"order":21307,...}}]}

# cancel everything still resting in the round
curl -s -X DELETE "https://seeryx.com/api/orders?slug=btc-updown-5m-1791916200" -H "X-Auth-Token: $TOKEN" -H "Idempotency-Key: $(uuidgen)"
# {"success":true,"cancelled":[21306,21307]}

Dividir y combinar

POST /api/split con { slug, amount } convierte amount USDC en otras tantas acciones de Sube y de Baja; POST /api/merge con { slug, shares } convierte los pares de nuevo en 1,00 $ cada uno. Sin comisión; al menos 5 pares; en seeryx.com se firman con un mensaje PMS1.

Efectivo y límites

  • Efectivo. Las compras en el libro no retienen efectivo, pero todas tus compras abiertas en un mercado, con la comisión taker a su precio límite, deben caber en tu efectivo disponible. El efectivo solo se mueve cuando una orden se ejecuta; una compra que ya no puedes pagar se cancela.
  • Tus propias órdenes. Una orden puede operar contra tus propias órdenes en el libro, y entonces paga la comisión taker como cualquier otra; una orden solo maker, en cambio, se rechaza.
  • Órdenes en el libro. Como máximo 200 por cuenta y 100 en un mismo mercado (400 open_orders_limit).
  • Frecuencia de solicitudes. 250 solicitudes de órdenes, cancelaciones, divisiones y combinaciones cada 10 segundos por cuenta; cuenta cada orden de un lote (429 rate_limited). Consulta Límites de solicitudes y errores.

Código

Órdenes límite, de mercado y en lote, cancelaciones, una división y una combinación, con seeryx.ts y chain.ts (o sus equivalentes en Python) al lado.

trading.ts
// trading.ts: limit, market and batch orders, cancels, split and merge. npx tsx trading.ts
import { api, loadWallet, signIn, type Book, type Round } from './seeryx';
import { signOrder, signPair, tradingSession, type Funds, type Order } from './chain';

const wallet = await loadWallet();
await signIn(wallet);
const funds = await api<Funds>('/funds');
// where GET /api/funds says onChainTrading (always on seeryx.com) every order carries `signed`
const session = funds.mode === 'chain' && funds.onChainTrading ? await tradingSession(funds, wallet) : null;
const sign = async (order: Order) => (session ? signOrder(funds, session, wallet.address, order) : order);
const place = async (order: Order) =>
  api<{ order: number | null }>('/orders', { method: 'POST', body: await sign(order) });
const { slug } = await api<Round>('/markets/BTC/5m/current');
const up = await api<Book>(`/orderbook/${slug}?side=up`), down = await api<Book>(`/orderbook/${slug}?side=down`);
const below = (book: Book, cents: number) => Math.max(1, Math.floor(book.asks[0]?.[0] ?? 50) - cents); // under the best ask

// limit: buy 10 Up shares 5c under the best ask, resting in the book; postOnly refuses it if it would trade at once
const limit = await place({
  slug, side: 'up', action: 'buy', type: 'limit', shares: 10, limit: below(up, 5), postOnly: true,
});

// market: spend up to $5 on Down, paying at most 2c over the best ask; what the book cannot fill is dropped
const cap = Math.min(99, Math.ceil(down.asks[0]?.[0] ?? 50) + 2);
const market = await place({ slug, side: 'down', action: 'buy', type: 'market', amount: 5, cap });
console.log({ limit, market });

// up to 15 orders in one request, placed in this order; each answer is what POST /orders would have said
const orders = await Promise.all([
  sign({ slug, side: 'up', action: 'buy', type: 'limit', shares: 5, limit: below(up, 10) }),
  sign({ slug, side: 'down', action: 'buy', type: 'limit', shares: 5, limit: below(down, 10) }),
]);
console.log({ batch: await api('/orders/batch', { method: 'POST', body: { orders } }) });

// cancel one order, then everything still resting in this round
if (limit.order) await api(`/orders/${limit.order}`, { method: 'DELETE' });
console.log({ cancelled: await api(`/orders?slug=${slug}`, { method: 'DELETE' }) });

// split $5 into 5 Up + 5 Down shares, then merge them back into $5
const pair = (merge: boolean) =>
  (session ? signPair(funds, session, wallet.address, slug, merge, 5) : undefined);
await api('/split', { method: 'POST', body: { slug, amount: 5, signed: await pair(false) } });
await api('/merge', { method: 'POST', body: { slug, shares: 5, signed: await pair(true) } });

Endpoints de órdenes

Todas las solicitudes de esta sección necesitan X-Auth-Token y una cabecera Idempotency-Key.

POST/api/orders

Colocar una orden

Con sesión + Idempotency-Key
CampoTipoDescripción
slugcuerpoobligatoriostringUna ronda que se opera (en vivo o próxima) o un mercado de eventos abierto
sidecuerpoobligatorioup | downEl resultado
actioncuerpoobligatoriobuy | sellUna venta necesita acciones que tengas y que ninguna otra venta haya reservado
typecuerpoobligatoriolimit | marketUna orden límite queda en el libro; una orden de mercado se ejecuta al instante y descarta el resto
sharescuerpoopcionalnumberÓrdenes límite y todas las ventas: acciones, con hasta 4 decimales
amountcuerpoopcionalnumberCompras de mercado: lo máximo que se gasta en USDC, comisión taker incluida
limitcuerpoopcionalnumberÓrdenes límite: el precio en centavos (consulta la cuadrícula de precios)
capcuerpoopcionalnumberÓrdenes de mercado: el peor precio en centavos, obligatorio con órdenes firmadas
postOnlycuerpoopcionalbooleanÓrdenes límite: rechaza la orden si alguna parte se ejecutaría al instante
signedcuerpoopcionalobjectLa orden firmada por tu clave de sesión de trading
Solicitud
curl -X POST "https://seeryx.com/api/orders" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"btc-updown-5m-1791916200","side":"up","action":"buy","type":"limit","shares":10,"limit":45,"postOnly":true}'
Respuesta
{ "order": 16901, "filled": 0, "remaining": 10, "spent": 0, "proceeds": 0 }
  • Cuando GET /api/funds indica onChainTrading (siempre en seeryx.com), el cuerpo lleva además "signed", creado por tu clave de sesión de trading: consulta Firma de órdenes.
  • order es el id de la parte que queda en el libro, null cuando no queda nada. filled son las acciones operadas ahora; spent y proceeds son los USDC pagados y recibidos, comisiones incluidas.
  • Una orden de mercado responde con su resultado completo: requested, fee, avgPrice (centavos, sin la comisión), unspent (en una compra) o unsold (en una venta), status "filled", "partial" o "none" y, si no se ejecutó por completo, un reason: "no_liquidity" (el libro se agotó), "beyond_limit" con bestPrice (el resto tiene un precio peor que tu cap) o "share_limit" (una compra de mercado firmada en acciones las obtuvo todas por debajo de su cap). Una orden de mercado que no ejecuta nada sigue siendo un 200.
EstadoCuándo
400Entrada no válida ("Invalid limit", "Invalid slug"), "Round is not live", "Round is closing", "Insufficient balance", "Insufficient free shares", una orden firmada que no coincide
400 below_minimumMenos acciones que minOrderShares; la respuesta añade "minimum"
400 would_takeUna orden solo maker que se ejecutaría al instante
400 open_orders_limitDemasiadas órdenes en el libro; la respuesta añade "limit": { account, round }
400 trading_pausedLa clave de sesión que la firmó se cerró: abre una sesión nueva y vuelve a firmar
429 rate_limitedMás solicitudes de órdenes de las permitidas por intervalo; espera "retryAfter" segundos
503 trading_haltedLas operaciones están detenidas para todos (consulta GET /api/notice); las cancelaciones siguen funcionando
503Exchange clock unavailable: el servidor no puede confirmar la hora de la ronda; inténtalo de nuevo en unos segundos
POST/api/orders/batch

Colocar hasta 15 órdenes en una sola solicitud

Con sesión + Idempotency-Key
CampoTipoDescripción
orderscuerpoobligatorioarrayDe 1 a 15 órdenes, cada una exactamente con el cuerpo de POST /api/orders y su propio objeto signed
Solicitud
curl -X POST "https://seeryx.com/api/orders/batch" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"orders":[{"slug":"btc-updown-5m-1791916200","side":"up","action":"buy","type":"limit","shares":5,"limit":40},{"slug":"btc-updown-5m-1791916200","side":"down","action":"buy","type":"limit","shares":5,"limit":0}]}'
Respuesta
{ "results": [{ "status": 200, "body": { "order": 21306, "filled": 0, "remaining": 5, "spent": 0, "proceeds": 0 } },
  { "status": 400, "body": { "error": "Invalid limit" } }] }
  • Se colocan en el orden indicado, cada una con sus propias comprobaciones; una orden rechazada no detiene las demás. Cada orden cuenta como una solicitud para el límite de solicitudes.
  • La orden i se registra con la clave de idempotencia <your key>-<i> (i desde 0; tu clave, de 125 caracteres como máximo), así que reintentar el lote entero no coloca nada dos veces.
EstadoCuándo
400orders no es una lista de 1 a 15 órdenes
429 rate_limitedEl lote superaría las solicitudes de órdenes permitidas por intervalo
DELETE/api/orders/:id

Cancelar una orden abierta

Con sesión + Idempotency-Key
CampoTipoDescripción
idrutaobligatorionumberId de la orden
Solicitud
curl -X DELETE "https://seeryx.com/api/orders/16901" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
Respuesta
{ "success": true }
EstadoCuándo
400Orden no encontrada: no es tuya o ya no está abierta
DELETE/api/orders

Cancelar todas tus órdenes abiertas, o las de un mercado

Con sesión + Idempotency-Key
CampoTipoDescripción
slugconsultaopcionalstringSolo esta ronda o este mercado de eventos
Solicitud
curl -X DELETE "https://seeryx.com/api/orders?slug=btc-updown-5m-1791916200" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
Respuesta
{ "success": true, "cancelled": [21306, 21307] }
  • Una solicitud y una transacción, sin importar cuántas órdenes haya.
POST/api/split

Convertir USDC en otras tantas acciones de Sube y de Baja

Con sesión + Idempotency-Key
CampoTipoDescripción
slugcuerpoobligatoriostringUn mercado que se opera
amountcuerpoobligatorionumberUSDC; 1 USDC da 1 acción de Sube + 1 de Baja
signedcuerpoopcionalobjectFirmado por la clave de sesión (PMS1)
Solicitud
curl -X POST "https://seeryx.com/api/split" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"btc-updown-5m-1791916200","amount":5}'
Respuesta
{ "success": true }
  • Al menos minOrderShares pares. Sin comisión.
EstadoCuándo
400 below_minimumMenos pares que el mínimo
400"Insufficient balance", una solicitud firmada que no coincide
POST/api/merge

Convertir pares de acciones de Sube y de Baja de nuevo en USDC

Con sesión + Idempotency-Key
CampoTipoDescripción
slugcuerpoobligatoriostringUn mercado que se opera
sharescuerpoobligatorionumberPares que se combinan; cada uno paga 1,00 $
signedcuerpoopcionalobjectFirmado por la clave de sesión (PMS1)
Solicitud
curl -X POST "https://seeryx.com/api/merge" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"btc-updown-5m-1791916200","shares":5}'
Respuesta
{ "success": true }
  • Al menos minOrderShares pares, o todos los pares que tengas. Sin comisión.