Startseite

API

Handel

Orders auf Seeryx platzieren, bündeln und stornieren: Limit-, Market- und Post-Only-Orders, Idempotenzschlüssel, Ablaufregeln, Aufteilen und Zusammenlegen.

Überblick

Du handelst mit POST /api/orders (eine Order) oder POST /api/orders/batch (bis zu 15), stornierst mit DELETE /api/orders/:id oder DELETE /api/orders und machst mit /api/split und /api/merge aus Guthaben Paare und zurück. Auf seeryx.com trägt jede Order, Aufteilung und Zusammenlegung ein signed-Objekt, erstellt von deinem Sitzungsschlüssel: Orders signieren zeigt, wie; die Beispiele auf dieser Seite erledigen das für dich.

Header und Idempotenz

FeldTypBeschreibung
X-Auth-TokenHeadererforderlichstringDas Anmelde-Token (oder Authorization: Bearer).
Idempotency-KeyHeadererforderlichstringBei jedem POST und DELETE, das handelt: 8–128 Buchstaben, Ziffern, _ oder -, neu für jeden Vorgang. Derselbe Schlüssel mit demselben Body liefert die Antwort der ersten Anfrage und ändert nichts; mit einem anderen Body wird er abgelehnt. Schlüssel werden 24 Stunden lang gespeichert.
Content-TypeHeadererforderlichstringapplication/json bei einem Body.

Ordertypen

TypFelderWas passiert
Limitshares, limitWird sofort gegen das ausgeführt, was zu ihrem Preis oder besser angeboten wird; der Rest liegt im Orderbuch, bis er ausgeführt wird, du ihn stornierst oder die Runde endet.
Limit, Post-Onlyshares, limit, postOnly: trueLiegt vollständig im Orderbuch oder wird abgelehnt (400 would_take): Sie nimmt nie Liquidität und zahlt daher nie die Taker-Gebühr.
Market-Kaufamount, capGibt sofort bis zu amount USDC (inklusive Gebühr) zu Preisen bis cap aus; der Rest verfällt und wird nie ins Orderbuch gelegt.
Market-Verkaufshares, capVerkauft sofort bis zu shares zu Preisen bis hinunter zu cap; der Rest verfällt.
FeldTypBeschreibung
slugerforderlichstringEine Runde, die gehandelt wird (live oder demnächst), oder ein offener Ereignismarkt.
sideerforderlichup | downDer Ausgang, den du handelst (in einem Ereignismarkt ist JA up und NEIN down).
actionerforderlichbuy | sellEin Verkauf braucht Anteile, die du hältst und die keine andere Verkaufsorder im Orderbuch reserviert hat.
typeerforderlichlimit | marketSiehe oben.
sharesoptionalnumberLimit-Orders und jeder Verkauf.
amountoptionalnumberMarket-Käufe: der Höchstbetrag in USDC, Taker-Gebühr inklusive.
limitoptionalnumberLimit-Orders: der Preis in Cent.
capoptionalnumberMarket-Orders: der schlechteste Preis in Cent. Ein Kauf zahlt nicht mehr, ein Verkauf nimmt nicht weniger.
postOnlyoptionalbooleanNur Limit-Orders.
signedoptionalobjectDie von deinem Sitzungsschlüssel signierte Order (Orders signieren).
Du willstBody (plus slug und signed)
10 Steigt zu 45¢ oder besser kaufen, im Orderbuch liegend{"side":"up","action":"buy","type":"limit","shares":10,"limit":45}
Jetzt bis zu 5 $ für Fällt ausgeben, höchstens 60¢ pro Anteil{"side":"down","action":"buy","type":"market","amount":5,"cap":60}
Jetzt 10 Steigt verkaufen, für mindestens 40¢{"side":"up","action":"sell","type":"market","shares":10,"cap":40}
10 Steigt zu 70¢ anbieten, nur als Maker{"side":"up","action":"sell","type":"limit","shares":10,"limit":70,"postOnly":true}

Die Antwort

Antworten
{ "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 }
Eine Limit-Order im Orderbuch; ein ausgeführter Market-Kauf über 5 $; ein Market-Kauf, dessen cap unter dem besten Verkaufsangebot lag.
  • order ist die ID dessen, was im Orderbuch liegt, null, wenn nichts liegt. filled sind die jetzt gehandelten Anteile; spent und proceeds sind gezahlte und erhaltene USDC, inklusive Gebühren.
  • Eine Market-Order ergänzt requested, fee, avgPrice (Cent, ohne Gebühr), unspent oder unsold, status (filled, partial oder none) und, wenn sie nicht vollständig ausgeführt wurde, reason: no_liquidity, beyond_limit (mit bestPrice) oder share_limit.
  • Eine Market-Order, die nichts ausführt, ist trotzdem ein 200, kein Fehler.

Ablauf und Rundenende

  • Limit-Orders werden bis zum Ende des Marktes signiert (dem Rundenende oder dem closesAt eines Ereignisses) und liegen bis dahin im Orderbuch.
  • Market-Orders, Aufteilungen und Zusammenlegungen werden innerhalb von Sekunden abgewickelt; signiere sie daher für 5 Minuten, nie über das Ende hinaus. Der Server akzeptiert einen Ablauf von 5 Sekunden in der Zukunft bis zum Ende.
  • In den letzten 5 Sekunden einer Runde werden keine neuen Orders angenommen (400 „Round is closing“). Orders im Orderbuch laufen am Rundenende ab und erscheinen in deiner Aktivität als Typ expire.
  • Kommende Runden. Die nächsten zehn 5m- und 15m-Runden (bei 1h und 1d die nächste) nehmen bereits Orders an, sodass ein Bot eine Runde vor ihrem Beginn quotieren kann.

Sammelorders und Stornierungen

POST /api/orders/batch platziert bis zu 15 Orders in einer Anfrage, in der angegebenen Reihenfolge, jede mit ihren eigenen Prüfungen: Die Antwort enthält ein { status, body } pro Order, genau das, was POST /api/orders geantwortet hätte. Order i wird unter <your key>-<i> gespeichert, sodass eine Wiederholung der ganzen Sammelorder mit demselben Schlüssel nichts doppelt platziert. DELETE /api/orders storniert alle deine offenen Orders oder, mit ?slug=, die eines Marktes, in einer Transaktion.

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

Aufteilen und Zusammenlegen

POST /api/split mit { slug, amount } macht aus amount USDC ebenso viele Steigt- und Fällt-Anteile; POST /api/merge mit { slug, shares } macht aus Paaren wieder je 1,00 $. Keine Gebühr; mindestens 5 Paare; auf seeryx.com mit einer PMS1-Nachricht signiert.

Guthaben und Limits

  • Guthaben. Kauforders im Orderbuch blockieren kein Guthaben, aber alle deine offenen Kauforders in einem Markt müssen, mit der Taker-Gebühr zu ihrem Limit, in dein verfügbares Guthaben passen. Guthaben bewegt sich nur, wenn eine Order ausgeführt wird; eine Kauforder, die du nicht mehr bezahlen kannst, wird storniert.
  • Deine eigenen Orders. Eine Order kann gegen deine eigenen Orders im Orderbuch ausgeführt werden und zahlt dann wie jede andere die Taker-Gebühr; Post-Only lehnt eine solche Order stattdessen ab.
  • Orders im Orderbuch. Höchstens 200 pro Konto und 100 in einem Markt (400 open_orders_limit).
  • Anfragerate. 250 Order-, Storno-, Aufteilungs- und Zusammenlegungsanfragen pro 10 Sekunden und Konto; jede Order einer Sammelorder zählt (429 rate_limited). Siehe Ratenlimits und Fehler.

Code

Limit-, Market- und Sammelorders, Stornierungen, eine Aufteilung und eine Zusammenlegung, mit seeryx.ts und chain.ts (oder ihren Python-Gegenstücken) daneben.

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

Order-Endpunkte

Jede Anfrage hier braucht X-Auth-Token und einen Idempotency-Key-Header.

POST/api/orders

Eine Order platzieren

Angemeldet + Idempotency-Key
FeldTypBeschreibung
slugBodyerforderlichstringEine Runde, die gehandelt wird (live oder demnächst), oder ein offener Ereignismarkt
sideBodyerforderlichup | downDer Ausgang
actionBodyerforderlichbuy | sellEin Verkauf braucht Anteile, die du hältst und die keine andere Verkaufsorder reserviert hat
typeBodyerforderlichlimit | marketEine Limit-Order liegt im Orderbuch; eine Market-Order wird sofort ausgeführt und verwirft den Rest
sharesBodyoptionalnumberLimit-Orders und jeder Verkauf: Anteile, bis zu 4 Nachkommastellen
amountBodyoptionalnumberMarket-Käufe: der Höchstbetrag in USDC, Taker-Gebühr inklusive
limitBodyoptionalnumberLimit-Orders: der Preis in Cent (siehe Preisraster)
capBodyoptionalnumberMarket-Orders: der schlechteste Preis in Cent, bei signierten Orders erforderlich
postOnlyBodyoptionalbooleanLimit-Orders: die Order ablehnen, wenn ein Teil davon sofort ausgeführt würde
signedBodyoptionalobjectDie von deinem Sitzungsschlüssel signierte Order
Anfrage
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}'
Antwort
{ "order": 16901, "filled": 0, "remaining": 10, "spent": 0, "proceeds": 0 }
  • Wo GET /api/funds onChainTrading meldet (auf seeryx.com immer), trägt der Body außerdem "signed", erstellt von deinem Sitzungsschlüssel: siehe „Orders signieren“.
  • order ist die ID des Teils, der im Orderbuch liegt, null, wenn nichts liegt. filled sind die jetzt gehandelten Anteile; spent und proceeds sind gezahlte und erhaltene USDC, inklusive Gebühren.
  • Eine Market-Order liefert ihr Ergebnis vollständig: requested, fee, avgPrice (Cent, ohne Gebühr), unspent (bei einem Kauf) oder unsold (bei einem Verkauf), status "filled", "partial" oder "none" und bei weniger als vollständiger Ausführung einen reason: "no_liquidity" (das Orderbuch war erschöpft), "beyond_limit" mit bestPrice (der Rest liegt preislich jenseits deines cap) oder "share_limit" (ein in Anteilen signierter Market-Kauf hat sie alle unterhalb seines cap erhalten). Eine Market-Order, die nichts ausführt, ist trotzdem ein 200.
StatusWann
400Ungültige Eingabe („Invalid limit“, „Invalid slug“), „Round is not live“, „Round is closing“, „Insufficient balance“, „Insufficient free shares“, eine signierte Order, die nicht übereinstimmt
400 below_minimumWeniger Anteile als minOrderShares; die Antwort ergänzt "minimum"
400 would_takeEine Post-Only-Order, die sofort ausgeführt würde
400 open_orders_limitZu viele Orders im Orderbuch; die Antwort ergänzt "limit": { account, round }
400 trading_pausedDer Sitzungsschlüssel, der sie signiert hat, wurde geschlossen: Öffne eine neue Sitzung und signiere erneut
429 rate_limitedMehr Order-Anfragen als pro Zeitfenster erlaubt; warte "retryAfter" Sekunden
503 trading_haltedDer Handel ist für alle angehalten (siehe GET /api/notice); Stornierungen funktionieren weiterhin
503„Exchange clock unavailable“: Der Server kann die Rundenzeit nicht bestätigen; versuche es in ein paar Sekunden erneut
POST/api/orders/batch

Bis zu 15 Orders in einer Anfrage platzieren

Angemeldet + Idempotency-Key
FeldTypBeschreibung
ordersBodyerforderlicharray1 bis 15 Orders, jede genau der Body von POST /api/orders mit ihrem eigenen signed-Objekt
Anfrage
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}]}'
Antwort
{ "results": [{ "status": 200, "body": { "order": 21306, "filled": 0, "remaining": 5, "spent": 0, "proceeds": 0 } },
  { "status": 400, "body": { "error": "Invalid limit" } }] }
  • In der angegebenen Reihenfolge platziert, jede mit ihren eigenen Prüfungen; eine abgelehnte Order hält die anderen nicht auf. Jede Order zählt als eine Anfrage für das Ratenlimit.
  • Order i wird unter dem Idempotenzschlüssel <your key>-<i> gespeichert (i ab 0; dein Schlüssel höchstens 125 Zeichen), sodass eine Wiederholung der ganzen Sammelorder nichts doppelt platziert.
StatusWann
400orders ist keine Liste von 1 bis 15 Orders
429 rate_limitedDie Sammelorder würde die pro Zeitfenster erlaubten Order-Anfragen überschreiten
DELETE/api/orders/:id

Eine offene Order stornieren

Angemeldet + Idempotency-Key
FeldTypBeschreibung
idPfaderforderlichnumberOrder-ID
Anfrage
curl -X DELETE "https://seeryx.com/api/orders/16901" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
Antwort
{ "success": true }
StatusWann
400Order nicht gefunden: nicht deine oder nicht mehr offen
DELETE/api/orders

Alle deine offenen Orders stornieren oder die eines Marktes

Angemeldet + Idempotency-Key
FeldTypBeschreibung
slugAbfrageoptionalstringNur diese Runde oder dieser Ereignismarkt
Anfrage
curl -X DELETE "https://seeryx.com/api/orders?slug=btc-updown-5m-1791916200" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
Antwort
{ "success": true, "cancelled": [21306, 21307] }
  • Eine Anfrage und eine Transaktion, egal wie viele Orders.
POST/api/split

Aus USDC ebenso viele Steigt- und Fällt-Anteile machen

Angemeldet + Idempotency-Key
FeldTypBeschreibung
slugBodyerforderlichstringEin Markt, der gehandelt wird
amountBodyerforderlichnumberUSDC; 1 USDC ergibt 1 Steigt- + 1 Fällt-Anteil
signedBodyoptionalobjectVom Sitzungsschlüssel signiert (PMS1)
Anfrage
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}'
Antwort
{ "success": true }
  • Mindestens minOrderShares Paare. Keine Gebühr.
StatusWann
400 below_minimumWeniger Paare als das Minimum
400„Insufficient balance“, eine signierte Anfrage, die nicht übereinstimmt
POST/api/merge

Paare aus Steigt- und Fällt-Anteilen wieder in USDC umwandeln

Angemeldet + Idempotency-Key
FeldTypBeschreibung
slugBodyerforderlichstringEin Markt, der gehandelt wird
sharesBodyerforderlichnumberZusammenzulegende Paare; jedes bringt 1,00 $
signedBodyoptionalobjectVom Sitzungsschlüssel signiert (PMS1)
Anfrage
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}'
Antwort
{ "success": true }
  • Mindestens minOrderShares Paare oder alle Paare, die du hältst. Keine Gebühr.