Transactions

A transaction represents any movement of value through Blacksheep.

Types

The type filter on transaction.getMany accepts all, buy, sell, withdraw, or deposit.

Lifecycle

Transactions progress through the following states:

• PENDING — accepted and queued
• COMPLETED — settled
• FAILED — could not be completed (insufficient funds, rejected by counterparty, etc.)
• CANCELLED — cancelled before settlement

Listen for state transitions via Webhooks — polling transaction.get works but is wasteful.

Retries

Mutating endpoints do not accept a client idempotency key — the request schema is strict and rejects unknown fields. A retried initiateSwap / submitWithdraw is a new transaction, so guard against duplicates on your side (e.g. don't resend until the first call returns a transaction id or errors). Each successful mutation returns its new transaction id; reconcile against that.

Reading transactions

• transaction.get — fetch a single transaction by id
• transaction.getMany — list, filterable by type, search, and recipient_id, with an optional limit (max 100). Returns { transactions, totals? }.