Overview

The Blacksheep API exposes a small set of resources that compose into every flow you'll build.

Accounts

Every API key belongs to an account (an organisation or individual). All resources — balances, transactions, external accounts, webhooks — are scoped to the account that owns the API key making the request.

Balances

A balance is the amount of a currency held under your account. You don't create balances directly — they accrue from deposits and swaps and are spent by withdrawals and swaps. See Listing balances.

Transactions

A transaction is the unit of movement. There are five types:

• deposit — funds in
• withdraw — funds out to an external account
• buy / sell — fiat ↔ crypto swap
• swap — currency conversion between two balances you hold

Transactions move through states. Subscribe to Webhooks to observe state changes.

External accounts

An external account is a third-party destination you can withdraw to:

• a bank account (for fiat)
• a wallet address (for crypto)

External accounts are created once, then reused on subsequent transaction.submitWithdraw calls by external_account_id.

Quotes

A quote is an indicative rate between two currencies. Fetch one before executing a transaction.initiateSwap to know what the user will receive.

Webhooks

A webhook is an HTTPS URL you register with us. We deliver signed event payloads to it when transactions are created or change (transaction.created, transaction.updated). See Webhooks.

Money representation

All amounts are serialized as:

{
    "value": "1500000",
    "code": "USDC",
    "decimals": 6,
    "chain": "ethereum"
}

value is a string-encoded integer in the smallest unit of the currency (cents for USD, wei for ETH, etc.); decimals gives the precision and code the asset. Crypto currencies also carry a chain. The string-encoded integer avoids floating-point precision loss.