API Reference

Authentication

The Flow API uses API keys to authenticate requests. You can generate keys in the dashboard under Settings → API Keys. Keys come in two scopes: live for production and test for sandbox. Keep your live keys secret and never commit them to source control.

Provide your key in the Authorization header:

curl https://api.flow.xyz/v1/transfers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 8c31d6b0"

Base URL

All endpoints are served from:

https://api.flow.xyz/v1

Sandbox traffic uses https://sandbox.api.flow.xyz/v1 and accepts sk_test_ keys. Sandbox is a full mirror of production — same endpoints, same response shapes, same error surfaces.

Idempotency

All POST endpoints accept an Idempotency-Key header. Re-posting with the same key within 24 hours returns the original response instead of creating a duplicate resource. Use a UUID per request.

Resources

Transfers

Move value between a source and destination. The source and destination can each be a bank account, wallet, stablecoin contract, or another Flow account.

POST /v1/transfers
{
  "source":      { "type": "bank", "id": "bank_8Ak..." },
  "destination": { "type": "wallet", "chain": "base", "address": "0x..." },
  "amount":      "10000.00",
  "currency":    "USD",
  "target":      "USDC"
}

Returns a Transfer object with a status of pending, settled, or failed. Subscribe to webhook events transfer.updated for status changes.

Payouts

Send value to a third-party recipient — payroll, vendor, marketplace seller, or creator. Payouts route through Borderless and deliver in local currency.

POST /v1/payouts
{
  "recipient_id": "recip_9Qn...",
  "amount":       "2500.00",
  "currency":     "MXN",
  "funding":      { "type": "balance", "id": "bal_usd" },
  "purpose":      "contractor_payment"
}

Quotes

Lock an FX rate for up to 60 seconds before committing to a transfer or payout. Quotes are free and don't count against your rate limit.

POST /v1/quotes
{
  "sell": "USD",
  "buy":  "BRL",
  "amount": "5000.00"
}

Recipients

Create recipients once and reference them by ID. Recipients encapsulate bank details, beneficial ownership, and compliance documents.

Webhooks

Register a webhook endpoint in the dashboard or via the API. Webhook payloads are signed with HMAC-SHA256 using your webhook secret — always verify the signature before processing.

POST https://your-app.com/webhooks/flow
X-Flow-Signature: t=1738000000,v1=...

{
  "id": "evt_...",
  "type": "transfer.settled",
  "data": { ... }
}

Errors

The API uses standard HTTP status codes. Error responses include a stable code you can match on programmatically:

400 — invalid_request: Malformed input or missing fields.
401 — unauthorized: Missing or invalid API key.
402 — insufficient_funds: Source has insufficient balance.
409 — idempotency_conflict: Same idempotency key used with different payload.
422 — compliance_block: Sanctions screening or policy rejection.
429 — rate_limited: Throttle — respect the Retry-After header.
5xx — Transient server errors. Retry with exponential backoff.

Rate limits

Default rate limit is 100 requests per second per API key. Bulk payout endpoints are limited separately at 20 requests per second. Contact support to raise limits for production workloads.

Versioning

The API is versioned via the URL path. We commit to no breaking changes within v1. Minor additive changes are published in the changelog and announced 30 days in advance.

One REST API for every flow of money.