Partner Integration API

Partner Integration API работает по модели «флоат»: партнёр — казино, букмекер или приложение — кладёт деньги на аккаунт-флоат в Yoyo Market (далее — Yoyo) и по API-ключу делает ставки за своих пользователей на рынках предсказаний Yoyo.

Каждый пользователь партнёра идентифицируется по external_user_id и автоматически маппится на суб-аккаунт Yoyo. Стейк каждой ставки фондируется с флоата, а полученные позиции идут в общий пул LMSR AMM.

Как это работает

1. Партнёр пополняет флоат. Аккаунт-флоат хранит нераспределённые средства партнёра.
2. Приходит ставка с external_user_id. Идентификатор сопоставляется с суб-аккаунтом Yoyo, который создаётся при первой ставке пользователя.
3. Стейк списывается с флоата. Затем сделка исполняется для этого суб-аккаунта.
4. Позиция идёт в общий LMSR-пул. Что такое позиция на рынке, описано на страницах Позиции и Рынки.
5. При продаже выплата зачисляется на суб-аккаунт. Она остаётся там: её можно использовать под следующие ставки или прочитать через Get User State.

Онбординг

1. Регистрация. Yoyo заводит партнёра и привязывает его к аккаунту-флоату.
2. Пополнение. Партнёр пополняет аккаунт-флоат обычным депозитом (крипта или карта).
3. Выпуск ключа. Партнёру выдают доступ к B2B-боту, и он один раз выпускает API-ключ командой /gen_key. Ключ показывается один раз и не перевыпускается — храните его в секрете.
4. Интеграция. Партнёр интегрирует перечисленные ниже эндпоинты.

Аутентификация

Все запросы требуют заголовок X-Partner-Key:

X-Partner-Key: pk_xxxxxxxxxxxxxxxxxxxxxxxx

Статус	Код	Описание
401	NO_PARTNER_KEY	Заголовок X-Partner-Key отсутствует.
401	INVALID_PARTNER_KEY	Ключ неверный или партнёр отключён.

Базовый URL

https://api.yoyo.market

Уточните хост под вашу среду. Это не базовый URL платформы, который используется в остальном Справочнике API.

Единицы и понятия

Поле	Описание
*_kopecks	Копейки. 1 RUB = 100 копеек.
shares	Акции позиции. 100 = 1 токен.
avg_price_bps	Цена входа в базисных пунктах. 10000 = 1 RUB.
fee_bps	Комиссия в базисных пунктах.
side	"yes" или "no".
external_user_id	Идентификатор пользователя в вашей системе.
client_bet_id	Ваш уникальный ключ идемпотентности.

Денежные поля этих эндпоинтов — целые числа. Общие для платформы соглашения о денежных значениях описаны на странице Формат денежных значений.

В остальной документации эти шкалы называются иначе: то, что здесь названо shares, там называется акциями в копейках, и 100 единиц и там и здесь составляют одну целую акцию, то есть токен. Цены там укладываются в тот же диапазон 0–10000, но описываются как вероятность, а не в базисных пунктах — см. Цены и вероятности.

Идемпотентность

Пара (partner, client_bet_id) уникальна. При сетевой ошибке или таймауте повторяйте запрос с тем же client_bet_id:

• Если ставка уже прошла, вернётся already_accepted — повторной сделки и повторного списания с флоата не будет.
• Если предыдущая попытка не исполнилась, резерв снят и повтор пройдёт штатно.

Формат ошибок

Для всех эндпоинтов используется единая структура ошибки:

{
  "error": {
    "code": "BET_LIMIT",
    "message": "amount_kopecks 500000 exceeds partner max bet 100000"
  }
}

Полный список кодов ошибок партнёрской интеграции см. в разделе Обработка ошибок.

Эндпоинты

Эндпоинт	Путь	Описание
Place Bet	POST /api/v1/partner/bets	Размещение ставки за пользователя партнёра; стейк списывается с флоата.
Sell Position	POST /api/v1/partner/sell	Продажа акций позиции с зачислением выплаты на суб-аккаунт.
Get Float Balance	GET /api/v1/partner/balance	Чтение баланса флоата и суммарного баланса всех суб-аккаунтов.
Get User State	GET /api/v1/partner/users/{external_user_id}	Чтение баланса и открытых позиций пользователя партнёра.

Остальная часть API платформы описана в Справочнике API.