головна сторінка

API

Торгівля

Розміщуйте, пакетно надсилайте й скасовуйте ордери на Seeryx: лімітні, ринкові й «лише мейкер», ключі ідемпотентності, строки дії, розділення й об’єднання.

Огляд

Торгуйте через POST /api/orders (один ордер) або POST /api/orders/batch (до 15), скасовуйте через DELETE /api/orders/:id або DELETE /api/orders, а перетворюйте кошти на пари й назад через /api/split і /api/merge. На seeryx.com кожен ордер, розділення й об’єднання містить об’єкт signed, створений ключем вашої торгової сесії: як це зробити, показано на сторінці «Підписання ордерів»; приклади на цій сторінці роблять це за вас.

Заголовки й ідемпотентність

ПолеТипОпис
X-Auth-Tokenзаголовокобов’язковеstringТокен входу (або Authorization: Bearer).
Idempotency-Keyзаголовокобов’язковеstringУ кожному торговому POST і DELETE: 8–128 літер, цифр, _ або -, новий для кожної дії. Той самий ключ із тим самим тілом повертає те, що відповів перший запит, і нічого не змінює; з іншим тілом запит відхиляється. Ключі зберігаються 24 години.
Content-Typeзаголовокобов’язковеstringapplication/json, якщо є тіло запиту.

Типи ордерів

ТипПоляЩо відбувається
Лімітнийshares, limitОдразу виконується проти пропозицій за його ціною або кращою, а залишок стоїть у книзі, доки не виконається, доки ви його не скасуєте або доки раунд не закриється.
Лімітний, «Лише мейкер»shares, limit, postOnly: trueСтає в книгу повністю або відхиляється (400 would_take): він ніколи не забирає ліквідність, тож ніколи не сплачує комісію тейкера.
Ринкова купівляamount, capОдразу витрачає до amount USDC (разом із комісією) за цінами не вище за cap; залишок відкидається й ніколи не стає в книгу.
Ринковий продажshares, capОдразу продає до shares часток за цінами не нижче за cap; залишок відкидається.
ПолеТипОпис
slugобов’язковеstringРаунд, що торгується (поточний або майбутній), чи відкритий подієвий ринок.
sideобов’язковеup | downРезультат, яким ви торгуєте (на подієвому ринку YES — це up, NO — down).
actionобов’язковеbuy | sellДля продажу потрібні частки, які у вас є і які не зарезервовано іншим ордером на продаж у книзі.
typeобов’язковеlimit | marketДив. вище.
sharesнеобов’язковеnumberЛімітні ордери й усі продажі.
amountнеобов’язковеnumberРинкові купівлі: найбільша сума USDC до витрати, разом із комісією тейкера.
limitнеобов’язковеnumberЛімітні ордери: ціна в центах.
capнеобов’язковеnumberРинкові ордери: найгірша ціна в центах. Купівля не платить більше, продаж не бере менше.
postOnlyнеобов’язковеbooleanЛише для лімітних ордерів.
signedнеобов’язковеobjectОрдер, підписаний ключем вашої сесії («Підписання ордерів»).
Ви хочетеТіло (плюс slug і signed)
Купити 10 «Вгору» за 45¢ або дешевше, з розміщенням у книзі{"side":"up","action":"buy","type":"limit","shares":10,"limit":45}
Витратити до 5 $ на «Вниз» зараз, щонайбільше 60¢ за частку{"side":"down","action":"buy","type":"market","amount":5,"cap":60}
Продати 10 «Вгору» зараз щонайменше за 40¢{"side":"up","action":"sell","type":"market","shares":10,"cap":40}
Виставити на продаж 10 «Вгору» за 70¢ лише як мейкер{"side":"up","action":"sell","type":"limit","shares":10,"limit":70,"postOnly":true}

Відповідь сервера

Відповіді
{ "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 }
Лімітний ордер, що став у книгу; виконана ринкова купівля на 5 $; ринкова купівля, у якої cap нижчий за найкращу ціну продажу.
  • order — ідентифікатор того, що стоїть у книзі, або null, якщо нічого не стоїть. filled — частки, проторговані зараз; spent і proceeds — сплачені й отримані USDC разом із комісіями.
  • Ринковий ордер додає requested, fee, avgPrice (центи, без комісії), unspent або unsold, status (filled, partial або none) і, якщо його виконано не повністю, reason: no_liquidity, beyond_limit (з bestPrice) або share_limit.
  • Ринковий ордер, який нічого не виконав, однаково повертає 200, а не помилку.

Термін дії й закриття

  • Лімітні ордери підписують до закриття ринку (кінця раунду або closesAt події), і вони стоять у книзі до цього моменту.
  • Ринкові ордери, розділення й об’єднання проходять розрахунок за лічені секунди, тож підписуйте їх на 5 хвилин, але ніколи не далі закриття. Сервер приймає термін дії від 5 секунд наперед до закриття.
  • За останні 5 секунд раунду нові ордери не приймаються (400 "Round is closing"). Строк дії ордерів у книзі завершується в момент закриття, і вони відображаються у вашій активності з типом expire.
  • Раунди наперед. Десять наступних раундів 5m і 15m (один для 1h і 1d) уже приймають ордери, тож бот може виставляти котирування для раунду ще до його початку.

Пакети й скасування

POST /api/orders/batch розміщує до 15 ордерів одним запитом, у заданому порядку, кожен зі своїми перевірками: відповідь містить по одному { status, body } на кожен ордер — рівно те, що відповів би POST /api/orders. Ордер i записується під <your key>-<i>, тож повторна спроба всього пакета з тим самим ключем нічого не розмістить двічі. DELETE /api/orders скасовує всі ваші відкриті ордери, а з ?slug= — ордери одного ринку, однією транзакцією.

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

Розділення й об’єднання

POST /api/split з { slug, amount } перетворює amount USDC на стільки ж часток «Вгору» і «Вниз»; POST /api/merge з { slug, shares } перетворює пари назад, по 1,00 $ за кожну. Без комісії; щонайменше 5 пар; на seeryx.com підписуються повідомленням PMS1.

Кошти й ліміти

  • Кошти. Ордери на купівлю в книзі не блокують коштів, але всі ваші відкриті купівлі на одному ринку разом із комісією тейкера за їхньою лімітною ціною мають покриватися вашими вільними коштами. Кошти рухаються лише тоді, коли ордер виконується; купівлю, яку ви вже не можете оплатити, скасовують.
  • Ваші власні ордери. Ордер може виконатися проти ваших власних ордерів у книзі й тоді сплачує комісію тейкера, як і будь-який інший; ордер «Лише мейкер» натомість відхиляється.
  • Ордери в книзі. Щонайбільше 200 на акаунт і 100 на одному ринку (400 open_orders_limit).
  • Частота запитів. 250 запитів на ордери, скасування, розділення й об’єднання за 10 секунд на акаунт; кожен ордер пакета враховується окремо (429 rate_limited). Див. «Ліміти запитів і помилки».

Код

Лімітні, ринкові й пакетні ордери, скасування, розділення й об’єднання; поруч мають лежати seeryx.ts і chain.ts (або їхні відповідники на Python).

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

Ендпоінти ордерів

Кожен запит цього розділу потребує X-Auth-Token і заголовка Idempotency-Key.

POST/api/orders

Розмістити ордер

Вхід + Idempotency-Key
ПолеТипОпис
slugтілообов’язковеstringРаунд, що торгується (поточний або майбутній), чи відкритий подієвий ринок
sideтілообов’язковеup | downРезультат
actionтілообов’язковеbuy | sellДля продажу потрібні частки, які у вас є і які не зарезервовано іншим продажем
typeтілообов’язковеlimit | marketЛімітний ордер стає в книгу; ринковий виконується одразу, а залишок відкидає
sharesтілонеобов’язковеnumberЛімітні ордери й усі продажі: частки, до 4 знаків після коми
amountтілонеобов’язковеnumberРинкові купівлі: найбільша сума USDC до витрати, разом із комісією тейкера
limitтілонеобов’язковеnumberЛімітні ордери: ціна в центах (див. сітку цін)
capтілонеобов’язковеnumberРинкові ордери: найгірша ціна в центах, обов’язкова для підписаних ордерів
postOnlyтілонеобов’язковеbooleanЛімітні ордери: відхилити ордер, якщо будь-яка його частина виконалася б одразу
signedтілонеобов’язковеobjectОрдер, підписаний ключем вашої торгової сесії
Запит
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}'
Відповідь
{ "order": 16901, "filled": 0, "remaining": 10, "spent": 0, "proceeds": 0 }
  • Якщо GET /api/funds повідомляє onChainTrading (на seeryx.com завжди), тіло також містить "signed", створений ключем вашої торгової сесії: див. «Підписання ордерів».
  • order — ідентифікатор частини, що стоїть у книзі, або null, якщо нічого не стоїть. filled — частки, проторговані зараз; spent і proceeds — сплачені й отримані USDC разом із комісіями.
  • Ринковий ордер повертає свій результат повністю: requested, fee, avgPrice (центи, без комісії), unspent (купівля) або unsold (продаж), status "filled", "partial" або "none", а якщо виконання неповне, — reason: "no_liquidity" (у книзі закінчилася ліквідність), "beyond_limit" з bestPrice (решта пропозицій дорожча за ваш cap) або "share_limit" (ринкова купівля, підписана в частках, отримала їх усі нижче за свій cap). Ринковий ордер, який нічого не виконав, однаково повертає 200.
СтатусКоли
400Неправильні вхідні дані ("Invalid limit", "Invalid slug"), "Round is not live", "Round is closing", "Insufficient balance", "Insufficient free shares", підписаний ордер, що не збігається з запитом
400 below_minimumМенше часток, ніж minOrderShares; відповідь додатково містить "minimum"
400 would_takeОрдер «Лише мейкер», який виконався б одразу
400 open_orders_limitЗабагато ордерів у книзі; відповідь додатково містить "limit": { account, round }
400 trading_pausedКлюч сесії, який його підписав, закрито: відкрийте нову сесію й підпишіть знову
429 rate_limitedПеревищено кількість запитів на ордери, дозволену за проміжок часу; зачекайте "retryAfter" секунд
503 trading_haltedТоргівлю зупинено для всіх (див. GET /api/notice); скасування й далі працюють
503Exchange clock unavailable: сервер не може підтвердити час раунду; спробуйте знову за кілька секунд
POST/api/orders/batch

Розмістити до 15 ордерів одним запитом

Вхід + Idempotency-Key
ПолеТипОпис
ordersтілообов’язковеarrayВід 1 до 15 ордерів, кожен — рівно тіло POST /api/orders із власним об’єктом signed
Запит
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}]}'
Відповідь
{ "results": [{ "status": 200, "body": { "order": 21306, "filled": 0, "remaining": 5, "spent": 0, "proceeds": 0 } },
  { "status": 400, "body": { "error": "Invalid limit" } }] }
  • Розміщуються в заданому порядку, кожен зі своїми перевірками; відхилений ордер не зупиняє решту. Кожен ордер враховується в ліміті частоти як один запит.
  • Ордер i записується під ключем ідемпотентності <your key>-<i> (i від 0; ваш ключ — не довше 125 символів), тож повторна спроба всього пакета нічого не розмістить двічі.
СтатусКоли
400orders — не список від 1 до 15 ордерів
429 rate_limitedПакет перевищив би кількість запитів на ордери, дозволену за проміжок часу
DELETE/api/orders/:id

Скасувати один відкритий ордер

Вхід + Idempotency-Key
ПолеТипОпис
idшляхобов’язковеnumberІдентифікатор ордера
Запит
curl -X DELETE "https://seeryx.com/api/orders/16901" \
  -H "X-Auth-Token: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
Відповідь
{ "success": true }
СтатусКоли
400Ордер не знайдено: він не ваш або вже не відкритий
DELETE/api/orders

Скасувати всі ваші відкриті ордери або ордери одного ринку

Вхід + Idempotency-Key
ПолеТипОпис
slugрядок запитунеобов’язковеstringЛише цей раунд або подієвий ринок
Запит
curl -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] }
  • Один запит і одна транзакція, хоч скільки б було ордерів.
POST/api/split

Перетворити USDC на стільки ж часток «Вгору» і «Вниз»

Вхід + Idempotency-Key
ПолеТипОпис
slugтілообов’язковеstringРинок, що торгується
amountтілообов’язковеnumberUSDC; 1 USDC дає 1 частку «Вгору» + 1 частку «Вниз»
signedтілонеобов’язковеobjectПідписано ключем сесії (PMS1)
Запит
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}'
Відповідь
{ "success": true }
  • Щонайменше minOrderShares пар. Без комісії.
СтатусКоли
400 below_minimumМенше пар, ніж мінімум
400"Insufficient balance", підписаний запит, що не збігається з тілом
POST/api/merge

Перетворити пари часток «Вгору» і «Вниз» назад на USDC

Вхід + Idempotency-Key
ПолеТипОпис
slugтілообов’язковеstringРинок, що торгується
sharesтілообов’язковеnumberПари для об’єднання; кожна приносить 1,00 $
signedтілонеобов’язковеobjectПідписано ключем сесії (PMS1)
Запит
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}'
Відповідь
{ "success": true }
  • Щонайменше minOrderShares пар або всі ваші пари. Без комісії.