Правила API

Посібники

Правила API

Застосовуйте ці спільні правила для signing, pagination, retries, errors і request tracing.

Точний підпис request

REST canonical string містить шість рядків:

text
METHOD
EXACT_REQUEST_TARGET
BODY_HASH
TIMESTAMP
NONCE
API_KEY_ID

EXACT_REQUEST_TARGET містить raw path і query точно у відправленому вигляді. Використовуйте method у верхньому регістрі, Unix timestamp у секундах, унікальний nonce і стандартний padded Base64 Ed25519 signature.

Для requests без body bytes canonical body-hash line залишається порожнім. Якщо body bytes присутні, обчисліть SHA-256 точних bytes і передайте lowercase hexadecimal digest у X-Api-Body-Hash. MPC initialization — задокументований staging-виняток: використовуйте явний zero-length form body та не додавайте hash header.

Cursor pagination

Більшість list endpoints повертають:

json
{
  "items": [],
  "nextCursor": null
}

Сприймайте cursors як opaque values. Передавайте точний nextCursor у наступний request і зупиняйтеся, коли він дорівнює null. Не декодуйте, не змінюйте й не використовуйте cursor з іншим набором filters.

Audit logs використовують page і limit. Під час pagination зберігайте незмінним snapshotAt.

Idempotency

Поточний Swagger вимагає X-Idempotency-Key для:

  • POST /api/v1/wallets;
  • POST /api/v1/transactions;
  • POST /api/v1/mpc/initialize;
  • POST /api/v1/co-signer/intents/{intentId}/claim;
  • POST /api/v1/co-signer/sessions/{sessionId}/messages.

Створюйте один key для кожної логічної операції. Після timeout або невідомого результату повторюйте ідентичний request із тим самим key. Ніколи не використовуйте його зі зміненими body bytes, path або parameters.

POST /api/v1/ledger/accounts наразі не документує fingerprint replay handling.

Модель помилки

Public REST errors мають формат:

json
{
  "code": "INVALID_QUERY_PARAMETER",
  "message": "Invalid query parameter",
  "details": [],
  "requestId": "a4b2b2d6-2c9d-4a04-a630-df669f1e93a0",
  "retryable": false
}

Використовуйте стабільний code, а не довільний message. Записуйте requestId для підтримки й враховуйте retryable перед повтором.

Значення HTTP status

StatusЗначення
400Некоректний request, query, cursor, date range або idempotency header
401Відсутня або некоректна signed authentication, clock skew, replay чи body-hash mismatch
403Обмеження IP, scope, організації або плану
404Ресурс не знайдено в межах організації
409Конфлікт idempotency, client reference, account reference або claim
413Payload завеликий
422Коректний JSON порушує domain rule
500Internal error
503Необхідний upstream service недоступний

Повторюйте request лише тоді, коли це дозволяють response і семантика операції. Для mutating operations зберігайте початковий idempotency key.

Request tracing і мова

Swagger документує необов’язкові x-request-id, x-lang та lang. Створюйте request ID на межі своєї системи й зберігайте його в усіх журналах. Не використовуйте language parameter для програмної логіки — автоматизація повинна спиратися на code.