API endpoints
Transactions API
Transaction endpoints створюють вихідні виведення та повертають ledger-backed записи депозитів, виведень, внутрішніх переказів і коригувань.
Операції
| Method | Path | Scope | Опис |
|---|---|---|---|
POST | /api/v1/transactions | withdrawals:create | Створення вихідної транзакції |
GET | /api/v1/transactions | transactions:read | Список транзакцій |
GET | /api/v1/transactions/{id} | transactions:read | Деталі транзакції |
POST | /api/v1/transactions/{id}/cancel | withdrawals:revoke | Скасування до початку виконання |
Створення виведення
POST /api/v1/transactions
Серед обов’язкових headers: X-Idempotency-Key і X-Api-Body-Hash.
{
"clientReference": "withdrawal-4821",
"walletId": "wallet-id",
"asset": "USDT",
"toAddress": "destination-address",
"amountAtomic": "1000000"
}Обов’язкові поля: walletId, asset, toAddress і amountAtomic. Необов’язковий clientReference приймає 1–128 символів. chainParams може містити визначені актуальною schema параметри конкретної мережі.
Завжди передавайте amountAtomic як base-10 string у найменшій одиниці активу. Не передавайте в цьому полі display decimal.
Деталі транзакції
Response визначає:
- рахунок і гаманець;
type:DEPOSIT,WITHDRAWAL,INTERNAL_TRANSFERабоADJUSTMENT;status:PENDING,CONFIRMED,FAILEDабоFAILED_ON_CHAIN;- atomic, display і signed amount та direction;
balanceEffects;- nullable
onChainDetails; networkFeeSummary;- nullable-проєкції
approvalіexecution; схвалення та підтвердження в блокчейні мають окремі стани; - client і billing references;
- timestamps створення та оновлення.
Фільтри списку
GET /api/v1/transactions приймає cursor, limit, accountId, walletId, clientReference, txHash, toAddress, chain, asset, status, type, createdFrom і createdTo.
Схвалення та скасування переказу
Вихідний переказ може мати approval.status=PENDING_APPROVAL, APPROVED, REJECTED, CANCELLED або PREPARATION_FAILED. Остаточне схвалення ще не є підтвердженням: перевіряйте execution.status для підписання, відправлення в мережу та підтвердження. Схвалений переказ усе ще може завершитися помилкою під час виконання. Режими external і auto_approve описано в посібнику Co-Signer.
Щоб скасувати переказ до початку виконання, надішліть POST /api/v1/transactions/{id}/cancel із точним JSON-тілом {} та X-Api-Body-Hash; потрібен дозвіл withdrawals:revoke. Успішна відповідь має статус CANCELLED. Якщо скасування збіглося з початком виконання, 409 APPROVAL_ALREADY_ACTIVATED означає, що цей метод уже не може зупинити переказ.
Безпечні повтори й конфлікти
Повторюйте request із невідомим результатом з тим самим idempotency key та ідентичними даними. Змінений request із тим самим ключем повертає 409 IDEMPOTENCY_CONFLICT. Дублікат clientReference може повернути 409 CLIENT_REFERENCE_CONFLICT.
Доменні помилки
Validation і domain failures включають UNSUPPORTED_CHAIN, UNSUPPORTED_ASSET, INVALID_ADDRESS, INVALID_FEE_LIMIT, INSUFFICIENT_AVAILABLE_BALANCE та WITHDRAWALS_BLOCKED.