Payments

Auto-topup rule and quiver state

Responses

• threshold_usd string (required)
• max_per_month integer (required)
• suspended boolean (required)
• consecutive_failures integer (required)
• quiver object (required)
• ready_value_usd string (required)
• used_this_month integer (required)
• arrows object[] (required)

Example

curl -X GET https://api.cofferline.com/v1/balance/auto-topup \
  -H "authorization: Bearer $TOKEN"

Configure auto-topup: a threshold plus pre-signed authorizations

Each authorization is a fixed-value EIP-3009 transferWithAuthorization to the treasury with a unique nonce — signed by the payer wallet, settleable exactly once, cancellable on-chain by the payer at any time. When a fee debit drops the balance below the threshold, the platform settles the oldest ready authorization and credits the balance. PUT replaces the rule (and re-arms a suspended one) and ADDS the given authorizations to the quiver; already-known nonces are skipped.

Request body

• threshold_usd string (required)
• max_per_month integer
• authorizations object[] (required)

Responses

Example

curl -X PUT https://api.cofferline.com/v1/balance/auto-topup \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"threshold_usd":"…","authorizations":[{"from":"…","to":"…","value":"…","valid_after":"…","valid_before":"…","nonce":"…","signature":"…"}]}'

Remove the auto-topup rule and its unsettled authorizations

Deletes the rule and every stored authorization. Settled credits stay on the ledger. Deleting here does not revoke the signatures cryptographically — the response's cancellation block carries everything the payer needs to void each outstanding nonce on-chain (sign CancelAuthorization over the given domain; anyone may submit).

Responses

• removed_authorizations integer (required)
• note string (required)
• cancellation object (required)

Example

curl -X DELETE https://api.cofferline.com/v1/balance/auto-topup \
  -H "authorization: Bearer $TOKEN"

Prepaid balance (Σ settled credits − Σ fee debits)

Responses

• balance_usd string (required)
• currency "USD" (required)

Example

curl -X GET https://api.cofferline.com/v1/balance \
  -H "authorization: Bearer $TOKEN"

Top up the prepaid balance via x402 (USDC, EIP-3009)

Without an X-PAYMENT header this answers 402 with exact-scheme payment requirements for the requested amount. Retry with the signed transferWithAuthorization: it settles on-chain first (real USDC to the treasury), then credits — the authorization nonce guarantees a retry can never double-credit. A durable pending-settlement record exists before anything is broadcast, so an interrupted request converges on exactly one credit (202 = outcome pending, reconciled from chain truth).

Request body

• amount_usd string (required)

Responses

• settlement_status "pending" (required)
• nonce string (required)
• value_usd string (required)
• remediation string (required)

Example

curl -X POST https://api.cofferline.com/v1/balance/topup \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"amount_usd":"…"}'