Ctrl K
GitHubDocs
Product: BabyFX Pay

Pay API reference

Last updated: 2026-07-23

Complete reference for the BabyFX Pay HTTP API. Base URL: http://localhost:4000 (local) or your public Pay host.

Authentication: every request except POST /v1/merchants requires Authorization: Bearer bfx_... (the api_key returned at merchant creation).

At a glance
Base path /v1
Content type application/json (request and response)
Auth Authorization: Bearer bfx_...
Idempotency Idempotency-Key: <opaque> on POST /v1/invoices
Rate limit 100 req/min per api_key (token bucket, configurable)
Errors RFC 7807 problem-details JSON

Merchants

POST /v1/merchants — create merchant

POST /v1/merchants
Content-Type: application/json

{
  "name": "Acme Coffee",
  "webhook_url": "https://acme.example.com/webhooks/babyfx",
  "settlement_address": "0xC6Fe5D33615a1C52c08018c47E8Bc53646A0E101"
}

Returns 201 with the merchant record including the one-time api_key and webhook_secret.

PUT /v1/merchant/settlement-address — update payout wallet

PUT /v1/merchant/settlement-address
Authorization: Bearer bfx_...
{ "settlement_address": "0x..." }

GET /v1/merchant — fetch current merchant

Returns the merchant record without api_key or webhook_secret (one-time at creation only).

Invoices

POST /v1/invoices — create invoice

POST /v1/invoices
Authorization: Bearer bfx_...
Idempotency-Key: pos-2026-06-22-1234


{ "fiat_amount": "4.50", "fiat_currency": "USD" }


POST /v1/invoices
Authorization: Bearer bfx_...


{ "baby_amount_wei": "1234567890000000000" }


POST /v1/invoices
Authorization: Bearer bfx_...


{
  "fiat_amount": "4.50",
  "fiat_currency": "USD",
  "metadata": { "order_id": "12345", "table": "7" }
}

Response 201:

{
  "id": "inv_a1b2c3d4",
  "merchant_id": 1,
  "deposit_address": "0x8e74c9d4...",
  "baby_amount_wei": "4500000000000000000",
  "fiat_amount": "4.50",
  "fiat_currency": "USD",
  "payment_uri": "ethereum:0x8e74c9d4@2027?value=4500000000000000000",
  "qr_code": "data:image/svg+xml;base64,...",
  "lookup_token": "lt_z9y8x7...",
  "status": "PENDING",
  "expires_at": "2026-06-22T13:00:00Z",
  "created_at": "2026-06-22T12:50:00Z"
}

GET /v1/invoices/{id} — fetch invoice

Returns the latest state, including status, paid_at, confirmations, sweep_status, and sweep_tx_hash when applicable.

GET /v1/invoices — list invoices

Query params: status, from, to, limit (max 200), cursor.

Error format

All errors are RFC 7807 problem-details:

{
  "type": "https://docs.babychain.com/errors/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Token bucket exhausted for this api_key",
  "instance": "/v1/invoices"
}
Status codes worth memorizing: 401 (bad or missing api_key), 409 (idempotency key reused with different payload), 422 (validation), 429 (rate limit), 503 (chain RPC unreachable).