Your first withdrawal

A withdrawal moves funds from your Blacksheep balance to an external account you've previously registered. This walks the minimum API surface.

1. Pick a destination

List the external accounts on your account:

POST /account.external.bank.getAll      # bank external accounts
POST /account.external.web3.getAll      # wallet external accounts

Each entry has an id. You'll pass it as external_account_id.

If you don't have one yet, create one via the dashboard. Programmatic creation is described in the API reference.

2. Execute the withdrawal

POST /transaction.submitWithdraw
Content-Type: application/json

{
    "external_account_id": "b21189d4-e549-4d77-b76b-85bfbb45d42d",
    "currency_out": { "value": "5000", "code": "USD", "decimals": 2 },
    "metadata": { "description": "Invoice INV-1024" }
}

metadata is optional and only supports a free-text description (not arbitrary correlation keys).

The response is the new transaction id, wrapped like every success response:

{ "data": "8f6f7d6f-1f57-4b4a-9b65-93f1f0a3b1c2" }

Like swaps, withdrawals settle asynchronously — poll transaction.get with the returned id (or await a webhook) for the final state.

3. Track settlement

Subscribe to webhooks (see Webhook setup) or poll transaction.get for the final state. Possible terminal states are COMPLETED, FAILED, or CANCELLED.

Common pitfalls

• Currency mismatch. A USD withdrawal must target a bank external account; a USDC withdrawal must target a wallet on a network that supports USDC. Mismatched requests are rejected.
• Insufficient balance. Check account.balance.getMany first if you're not certain.
• Unverified external account. Bank external accounts must be verified before they can receive funds. Verification status is on the external account object.