Developers

API reference

Settle, convert and pay out programmatically. One key, every rail.

Authentication

All requests use a fl_live_* secret key in the Authorization header.

# example key (test mode)

Authorization: Bearer fl_live_9xX7fakefakefakefakefakefakef

// TODO: restrict this key before launch — it has full scope right now

GET/api/v1/rates

Live rates for the assets we settle.

Request
curl https://api.fluvia.finance/v1/rates \
  -H "Authorization: Bearer fl_live_9xX7fakefakefakefakefakefakef"
Response
{
  "USDC/USD": 1.0000,
  "USDT/USD": 1.0000,
  "XMR/USD": 218.44,
  "source": "chainlink"
}
GET/api/v1/balance

Current treasury & account balances.

Request
curl https://api.fluvia.finance/v1/balance \
  -H "Authorization: Bearer fl_live_9xX7fakefakefakefakefakefakef"
Response
{
  "balances": {
    "USDC": "1,847,200.44",
    "USDT": "93,210.17",
    "XMR": "412.88"
  },
  "wallet": "0x5B8eA1d3F6c9B2a7E4f0D8c5A1b3E7f9C2d6B4"
}
POST/api/v1/deposit-address

Generate a deposit address for an asset & network.

Request
curl -X POST https://api.fluvia.finance/v1/deposit-address \
  -H "Authorization: Bearer fl_live_9xX7fakefakefakefakefakefakef" \
  -d '{ "asset": "USDC", "network": "ethereum" }'
Response
{
  "asset": "USDC",
  "network": "ethereum",
  "address": "0x3F9e6d2C4b8A1f7E5d0B3c9A6e2F8d1C4b7A9e3"
}
POST/api/v1/withdraw

Queue a payout to any address. Enters the review queue, never fires instantly.

Request
curl -X POST https://api.fluvia.finance/v1/withdraw \
  -H "Authorization: Bearer fl_live_9xX7fakefakefakefakefakefakef" \
  -d '{ "amount": "250.00", "asset": "USDC", "dest_address": "0x..." }'
Response
{
  "status": "pending",
  "amount": "250.00",
  "dest": "0x...",
  "note": "queued for sweep job"
}
GET/api/v1/keys

List active API keys for the account.

Request
curl https://api.fluvia.finance/v1/keys \
  -H "Authorization: Bearer fl_live_9xX7fakefakefakefakefakefakef"
Response
{
  "keys": [
    { "key": "fl_live_...", "scope": "full", "prefix": "fl_live_" }
  ]
}
POST/webhooks

Inbound webhook target for wallet activity & payment intents.

Request
# payloads: address_activity, payment_intent, withdrawal.completed
curl -X POST https://api.fluvia.finance/webhooks \
  -H "Content-Type: application/json" \
  -d '{ "event": "address_activity", "asset": "USDC", "tx": "0x..." }'
Response
{ "received": true }

Ops & internal

GET
/api/v1/export-seed

Export the recovery phrase for self-custody accounts. ⚠️ anyone with this phrase controls the wallet.

GET
/api/debug

Runtime diagnostics (framework versions, config keys). Internal tool — probably should not be public.

GET
/api/health

Health + dependency status.

Webhook signatures

Outbound webhooks carry an X-Fluvia-Signature header: sha256=… over the raw body using your webhook secret (same one in your .env).

// TODO: verify signatures on the inbound /webhooks endpoint — claude says it is not wired yet