Створення транзакції

Посібники

Створення транзакції

Створіть вихідну транзакцію з наявного гаманця BroSettlement. Успішний `POST` означає, що транзакцію прийнято в обробку, але ще не підтверджено в мережі.

Перед початком

Потрібні:

  • Гаманець у статусі ACTIVE та його walletId
  • Актив, який зараз повертає GET /api/v1/assets
  • Коректна адреса отримувача для вибраної мережі
  • Достатній availableBalance для суми та можливої мережевої комісії
  • Ініціалізований MPC і справний Co-Signer
  • API-ключ зі scope withdrawals:create
  • Унікальний X-Idempotency-Key
  • Необов’язковий, але рекомендований унікальний clientReference з вашої системи

1. Перевірте гаманець і доступний баланс

Перед створенням транзакції отримайте гаманець і його баланси:

text
GET /api/v1/wallets/{walletId}
GET /api/v1/wallets/{walletId}/balances

Для перевірки доступної суми використовуйте availableBalance. Не вважайте весь posted balance доступним, якщо його частину зарезервовано.

2. Перетворіть суму в atomic units

Передавайте amountAtomic як десятковий рядок у найменших одиницях активу. Не використовуйте числа з плаваючою комою для сум.

Наприклад, якщо USDT має 6 знаків після коми:

text
1.00 USDT = "1000000"

Отримуйте актуальну кількість знаків і доступність мережі через Assets API, а не з hard-coded значень.

3. Сформуйте request body

json
{
  "clientReference": "withdrawal-4821",
  "walletId": "wallet-id",
  "asset": "USDT",
  "toAddress": "destination-address",
  "amountAtomic": "1000000"
}

clientReference пов’язує транзакцію BroSettlement із вашим замовленням, виплатою або заявкою на виведення. Якщо поле передано, значення має бути унікальним.

Використовуйте chainParams лише тоді, коли поточна API-схема вимагає параметри вибраної мережі. Не переносьте параметри між різними мережами.

4. Підпишіть і надішліть точний запит

bash
curl https://brosettlement-staging-api.brolabel.io/api/v1/transactions \
  -X POST \
  -H "X-Api-Key-Id: 11111111-2222-4333-8444-555555555555" \
  -H "X-Api-Timestamp: 1785402000" \
  -H "X-Api-Nonce: 37c19dc0-8247-4a56-8193-beca10dce927" \
  -H "X-Api-Signature: base64_ed25519_signature" \
  -H "X-Api-Body-Hash: sha256_of_exact_body" \
  -H "X-Idempotency-Key: 018f4df0-5a7f-7352-bd4a-5fd069c2a0c2" \
  -H "Content-Type: application/json" \
  -d '{"clientReference":"withdrawal-4821","walletId":"wallet-id","asset":"USDT","toAddress":"destination-address","amountAtomic":"1000000"}'

Обчислюйте body hash з точних body bytes, які надсилає HTTP client. Підписуйте канонічний шестирядковий рядок із точним методом POST, request target /api/v1/transactions, body hash, timestamp, nonce та API key ID.

5. Збережіть прийняту транзакцію

Успішний запит повертає 201 Created з деталями транзакції. Збережіть щонайменше:

  • id
  • walletId
  • type
  • status
  • chain
  • asset
  • amountAtomic
  • clientReference
  • createdAt і updatedAt

Початковий статус зазвичай PENDING. Збережіть BroSettlement transaction id до того, як повертати успішний результат у власному процесі.

6. Відстежте транзакцію до кінцевого статусу

Обробляйте transaction.created, transaction.updated, transaction.confirmed, transaction.failed і transaction.failed_on_chain. Звіряйте кожну подію через:

text
GET /api/v1/transactions/{transactionId}

REST є джерелом істини. Не позначайте виплату завершеною лише на основі відповіді 201. Кінцеві статуси: CONFIRMED, FAILED і FAILED_ON_CHAIN.

Безпечний повтор запиту

Якщо результат початкового запиту невідомий, повторіть його з тим самим X-Idempotency-Key і повністю ідентичним request body. Зміна body з повторним використанням ключа поверне IDEMPOTENCY_CONFLICT.

Не створюйте новий idempotency key, доки не перевірите початкову транзакцію за id, clientReference або у списку транзакцій.

Поширені помилки

Код помилкиЩо перевірити
INSUFFICIENT_AVAILABLE_BALANCEПеревірте доступну суму та можливу мережеву комісію.
INVALID_ADDRESSПеревірте адресу отримувача для вибраної мережі.
UNSUPPORTED_ASSET або UNSUPPORTED_CHAINОновіть актуальний каталог активів і мереж.
WITHDRAWALS_BLOCKEDПрипиніть повтори й усуньте обмеження організації або гаманця.
CLIENT_REFERENCE_CONFLICTВикористайте наявну транзакцію або створіть справді новий бізнес-ідентифікатор.
IDEMPOTENCY_CONFLICTПовторюйте лише точний початковий запит.
UPSTREAM_UNAVAILABLEЗбережіть початковий idempotency key і повторіть запит із backoff.

Transactions API

Перегляньте повну схему запиту й відповіді, фільтри, статуси та вплив на баланс.

WebSocket-події

Реалізуйте відновлювану й ідемпотентну обробку подій життєвого циклу.

Правила API

Перегляньте канонічний підпис, ідемпотентність, повтори, помилки та трасування запитів.