Transactions API

API endpoints

Transactions API

Transaction endpoints створюють вихідні виведення та повертають ledger-backed записи депозитів, виведень, внутрішніх переказів і коригувань.

Операції

MethodPathScopeОпис
POST/api/v1/transactionswithdrawals:createСтворення вихідної транзакції
GET/api/v1/transactionstransactions:readСписок транзакцій
GET/api/v1/transactions/{id}transactions:readДеталі транзакції
POST/api/v1/transactions/{id}/cancelwithdrawals:revokeСкасування до початку виконання

Створення виведення

POST /api/v1/transactions

Серед обов’язкових headers: X-Idempotency-Key і X-Api-Body-Hash.

json
{
  "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.