pagina iniziale

API

Trading

Inserisci, raggruppa e annulla ordini su Seeryx: ordini limite, a mercato e post-only, chiavi di idempotenza, scadenze, Dividi e Unisci, con esempi di codice.

Panoramica

Fai trading con POST /api/orders (un ordine) o POST /api/orders/batch (fino a 15), annulli con DELETE /api/orders/:id o DELETE /api/orders, e trasformi i fondi in coppie e viceversa con /api/split e /api/merge. Su seeryx.com ogni ordine, divisione e unione include un oggetto signed creato dalla tua chiave di sessione di trading: Firma degli ordini mostra come; gli esempi di questa pagina lo fanno per te.

Intestazioni e idempotenza

CampoTipoDescrizione
X-Auth-TokenintestazioneobbligatoriostringIl token di accesso (oppure Authorization: Bearer).
Idempotency-KeyintestazioneobbligatoriostringIn ogni POST e DELETE che fa trading: da 8 a 128 caratteri tra lettere, cifre, _ o -, nuova per ogni operazione distinta. La stessa chiave con lo stesso corpo restituisce la risposta della prima richiesta e non cambia nulla; con un corpo diverso viene rifiutata. Le chiavi vengono ricordate per 24 ore.
Content-Typeintestazioneobbligatoriostringapplication/json quando c’è un corpo.

Tipi di ordine

TipoCampiCosa succede
Limiteshares, limitViene eseguito subito contro ciò che è offerto al suo prezzo o a un prezzo migliore, e il resto rimane nel libro ordini finché non viene eseguito, non lo annulli o il round non chiude.
Limite, post onlyshares, limit, postOnly: trueEntra per intero nel libro ordini o viene rifiutato (400 would_take): non prende mai liquidità, quindi non paga mai la commissione taker.
Acquisto a mercatoamount, capSpende subito fino ad amount USDC (commissione inclusa) a prezzi fino a cap; il resto viene scartato, mai lasciato nel libro ordini.
Vendita a mercatoshares, capVende subito fino a shares azioni a prezzi non inferiori a cap; il resto viene scartato.
CampoTipoDescrizione
slugobbligatoriostringUn round negoziabile (in corso o futuro) o un mercato su un evento aperto.
sideobbligatorioup | downL’esito che negozi (in un mercato su un evento, YES è up e NO è down).
actionobbligatoriobuy | sellUna vendita richiede azioni che possiedi e che nessun’altra vendita in attesa ha già riservato.
typeobbligatoriolimit | marketVedi sopra.
sharesfacoltativonumberOrdini limite e tutte le vendite.
amountfacoltativonumberAcquisti a mercato: il massimo in USDC da spendere, commissione taker inclusa.
limitfacoltativonumberOrdini limite: il prezzo in centesimi.
capfacoltativonumberOrdini a mercato: il prezzo peggiore in centesimi. Un acquisto non paga di più, una vendita non incassa di meno.
postOnlyfacoltativobooleanSolo ordini limite.
signedfacoltativoobjectL’ordine firmato dalla tua chiave di sessione (Firma degli ordini).
VuoiCorpo (più slug e signed)
Comprare 10 Su a 45¢ o a un prezzo migliore, in attesa nel libro ordini{"side":"up","action":"buy","type":"limit","shares":10,"limit":45}
Spendere subito fino a 5 $ su Giù, al massimo 60¢ per azione{"side":"down","action":"buy","type":"market","amount":5,"cap":60}
Vendere subito 10 Su, ad almeno 40¢{"side":"up","action":"sell","type":"market","shares":10,"cap":40}
Offrire 10 Su a 70¢, solo come maker{"side":"up","action":"sell","type":"limit","shares":10,"limit":70,"postOnly":true}

La risposta

Risposte
{ "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 }
Un ordine limite in attesa; un acquisto a mercato da 5 $ eseguito; un acquisto a mercato il cui cap era sotto il miglior prezzo in vendita.
  • order è l’id di ciò che resta nel libro ordini, null quando non resta nulla. filled sono le azioni negoziate subito; spent e proceeds sono gli USDC pagati e ricevuti, commissioni incluse.
  • Un ordine a mercato aggiunge requested, fee, avgPrice (centesimi, senza commissione), unspent o unsold, status (filled, partial o none) e, quando non è stato eseguito per intero, reason: no_liquidity, beyond_limit (con bestPrice) o share_limit.
  • Un ordine a mercato che non viene eseguito affatto restituisce comunque 200, non un errore.

Scadenza e chiusura

  • Gli ordini limite sono firmati fino alla chiusura del mercato (la fine del round, o il closesAt di un evento) e restano nel libro ordini fino ad allora.
  • Ordini a mercato, divisioni e unioni vengono regolati in pochi secondi, quindi firmali per 5 minuti, mai oltre la chiusura. Il server accetta una scadenza compresa tra 5 secondi da adesso e la chiusura.
  • Negli ultimi 5 secondi di un round non si accettano nuovi ordini (400 "Round is closing"). Gli ordini in attesa scadono alla chiusura e compaiono con il tipo expire nella tua attività.
  • Round futuri. I prossimi dieci round da 5m e da 15m (uno per 1h e 1d) accettano già ordini, quindi un bot può quotare un round prima che inizi.

Ordini in blocco e annullamenti

POST /api/orders/batch inserisce fino a 15 ordini in una sola richiesta, nell’ordine dato, ciascuno con i propri controlli: la risposta contiene un { status, body } per ordine, esattamente quello che avrebbe risposto POST /api/orders. L’ordine i viene registrato sotto <your key>-<i>, quindi ripetere l’intero blocco con la stessa chiave non inserisce nulla due volte. DELETE /api/orders annulla tutti i tuoi ordini aperti, o con ?slug= quelli di un solo mercato, in un’unica transazione.

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]}

Divisione e unione

POST /api/split con { slug, amount } trasforma amount USDC in altrettante azioni Su e Giù; POST /api/merge con { slug, shares } ritrasforma ogni coppia in 1,00 $. Nessuna commissione; almeno 5 coppie; su seeryx.com si firma con un messaggio PMS1.

Fondi e limiti

  • Fondi disponibili. Gli acquisti in attesa non bloccano fondi, ma tutti i tuoi acquisti aperti in un mercato, con la commissione taker al loro prezzo limite, devono rientrare nei tuoi fondi disponibili. I fondi si muovono solo quando un ordine viene eseguito; un acquisto che non puoi più pagare viene annullato.
  • I tuoi ordini. Un ordine può essere eseguito contro i tuoi stessi ordini in attesa e in tal caso paga la commissione taker come qualsiasi altro; post only invece rifiuta un ordine del genere.
  • Ordini in attesa. Al massimo 200 per conto e 100 in un singolo mercato (400 open_orders_limit).
  • Frequenza delle richieste. 250 richieste di ordine, annullamento, divisione e unione ogni 10 secondi per conto; conta ogni ordine di un blocco (429 rate_limited). Vedi Limiti di richieste ed errori.

Codice

Ordini limite, a mercato e in blocco, annullamenti, una divisione e un’unione, con seeryx.ts e chain.ts (o i loro equivalenti Python) nella stessa cartella.

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) } });

Endpoint degli ordini

Ogni richiesta di questa sezione richiede X-Auth-Token e un’intestazione Idempotency-Key.

POST/api/orders

Inserisci un ordine

Con accesso + Idempotency-Key
CampoTipoDescrizione
slugcorpoobbligatoriostringUn round negoziabile (in corso o futuro) o un mercato su un evento aperto
sidecorpoobbligatorioup | downL’esito
actioncorpoobbligatoriobuy | sellUna vendita richiede azioni che possiedi e che nessun’altra vendita ha riservato
typecorpoobbligatoriolimit | marketUn ordine limite resta in attesa; un ordine a mercato viene eseguito subito e scarta il resto
sharescorpofacoltativonumberOrdini limite e tutte le vendite: azioni, fino a 4 decimali
amountcorpofacoltativonumberAcquisti a mercato: il massimo in USDC da spendere, commissione taker inclusa
limitcorpofacoltativonumberOrdini limite: il prezzo in centesimi (vedi la griglia dei prezzi)
capcorpofacoltativonumberOrdini a mercato: il prezzo peggiore in centesimi, obbligatorio con gli ordini firmati
postOnlycorpofacoltativobooleanOrdini limite: rifiuta l’ordine se una sua parte verrebbe eseguita subito
signedcorpofacoltativoobjectL’ordine firmato dalla tua chiave di sessione di trading
Richiesta
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}'
Risposta
{ "order": 16901, "filled": 0, "remaining": 10, "spent": 0, "proceeds": 0 }
  • Dove GET /api/funds indica onChainTrading (sempre su seeryx.com), il corpo include anche "signed", creato dalla tua chiave di sessione di trading: vedi Firma degli ordini.
  • order è l’id della parte che resta nel libro ordini, null quando non resta nulla. filled sono le azioni negoziate subito; spent e proceeds sono gli USDC pagati e ricevuti, commissioni incluse.
  • Un ordine a mercato restituisce il suo risultato completo: requested, fee, avgPrice (centesimi, senza commissione), unspent (un acquisto) o unsold (una vendita), status "filled", "partial" o "none" e, se non è stato eseguito per intero, un reason: "no_liquidity" (il libro ordini si è esaurito), "beyond_limit" con bestPrice (il resto ha un prezzo oltre il tuo cap) o "share_limit" (un acquisto a mercato firmato in azioni le ha ottenute tutte sotto il suo cap). Un ordine a mercato che non viene eseguito affatto restituisce comunque 200.
StatoQuando
400Input non valido ("Invalid limit", "Invalid slug"), "Round is not live", "Round is closing", "Insufficient balance", "Insufficient free shares", un ordine firmato che non corrisponde
400 below_minimumMeno azioni di minOrderShares; la risposta aggiunge "minimum"
400 would_takeUn ordine post-only che verrebbe eseguito subito
400 open_orders_limitTroppi ordini in attesa; la risposta aggiunge "limit": { account, round }
400 trading_pausedLa chiave di sessione che l’ha firmato è stata chiusa: apri una nuova sessione e firma di nuovo
429 rate_limitedPiù richieste di ordine di quelle consentite per finestra temporale; attendi "retryAfter" secondi
503 trading_haltedIl trading è sospeso per tutti (vedi GET /api/notice); gli annullamenti funzionano comunque
503Orologio della piattaforma non disponibile ("Exchange clock unavailable"): il server non può confermare l’orario del round; riprova tra qualche secondo
POST/api/orders/batch

Inserisci fino a 15 ordini in una sola richiesta

Con accesso + Idempotency-Key
CampoTipoDescrizione
orderscorpoobbligatorioarrayDa 1 a 15 ordini, ciascuno esattamente il corpo di POST /api/orders con il proprio oggetto signed
Richiesta
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}]}'
Risposta
{ "results": [{ "status": 200, "body": { "order": 21306, "filled": 0, "remaining": 5, "spent": 0, "proceeds": 0 } },
  { "status": 400, "body": { "error": "Invalid limit" } }] }
  • Inseriti nell’ordine dato, ciascuno con i propri controlli; un ordine rifiutato non blocca gli altri. Ogni ordine conta come una richiesta ai fini del limite di richieste.
  • L’ordine i viene registrato sotto la chiave di idempotenza <your key>-<i> (i parte da 0; la tua chiave al massimo di 125 caratteri), quindi ripetere l’intero blocco non inserisce nulla due volte.
StatoQuando
400orders non è un elenco da 1 a 15 ordini
429 rate_limitedIl blocco supererebbe le richieste di ordine consentite per finestra temporale
DELETE/api/orders/:id

Annulla un ordine aperto

Con accesso + Idempotency-Key
CampoTipoDescrizione
idpercorsoobbligatorionumberId dell’ordine
Richiesta
curl -X DELETE "https://seeryx.com/api/orders/16901" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
Risposta
{ "success": true }
StatoQuando
400Ordine non trovato: non è tuo o non è più aperto
DELETE/api/orders

Annulla tutti i tuoi ordini aperti, o quelli di un mercato

Con accesso + Idempotency-Key
CampoTipoDescrizione
slugquery stringfacoltativostringSolo questo round o mercato su un evento
Richiesta
curl -X DELETE "https://seeryx.com/api/orders?slug=btc-updown-5m-1791916200" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
Risposta
{ "success": true, "cancelled": [21306, 21307] }
  • Una richiesta e una transazione, qualunque sia il numero di ordini.
POST/api/split

Trasforma USDC in altrettante azioni Su e Giù

Con accesso + Idempotency-Key
CampoTipoDescrizione
slugcorpoobbligatoriostringUn mercato negoziabile
amountcorpoobbligatorionumberUSDC; 1 USDC produce 1 azione Su + 1 azione Giù
signedcorpofacoltativoobjectFirmato dalla chiave di sessione (PMS1)
Richiesta
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}'
Risposta
{ "success": true }
  • Almeno minOrderShares coppie. Nessuna commissione.
StatoQuando
400 below_minimumMeno coppie del minimo
400"Insufficient balance", una richiesta firmata che non corrisponde
POST/api/merge

Ritrasforma coppie di azioni Su e Giù in USDC

Con accesso + Idempotency-Key
CampoTipoDescrizione
slugcorpoobbligatoriostringUn mercato negoziabile
sharescorpoobbligatorionumberCoppie da unire; ciascuna paga 1,00 $
signedcorpofacoltativoobjectFirmato dalla chiave di sessione (PMS1)
Richiesta
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}'
Risposta
{ "success": true }
  • Almeno minOrderShares coppie, o tutte le coppie che possiedi. Nessuna commissione.