Settlement overview

​

The layers

┌───────────────────────────────────────┐
│ Transfers  (logical — app-visible)    │   Partner creates via /v1/transfers
├───────────────────────────────────────┤
│ Settlement Rules  (when to settle)    │   Thresholds, schedules, manual
├───────────────────────────────────────┤
│ Settlement Windows  (batch cadence)   │   Hourly / daily / custom
├───────────────────────────────────────┤
│ Execution  (actual rail moves)        │   ACH, wire, stablecoin transfers
├───────────────────────────────────────┤
│ Reconciliation  (match internal→rail) │   Catch drift, gaps
└───────────────────────────────────────┘

​

Default behavior

• Settles same-currency internal transfers instantly (just a ledger move)
• Settles cross-border / cross-rail transfers at the next settlement window — default every 4 hours for most rails
• Takes configurable fees (default x402FeePercentage: 0.029 = 2.9% on x402 volume, zero on other flows)
• Reconciles nightly against rail settlement files

• You want instant settlement for specific rails
• You want different cadence per merchant / agent
• You need rule-based routing (auto-sweep balances, split fees)
• Your accounting team needs matched reconciliation

​

What lives in this section

​

Tenant-level configuration

curl https://api.getsly.ai/v1/settlement/config \
  -H "Authorization: Bearer pk_live_..."

{
  "x402FeePercentage": 0.029,
  "autoSettlementEnabled": true,
  "settlementSchedule": "immediate",
  "holdbackPercentage": 0.00,
  "reserveAmount": "0.00"
}

curl -X PATCH https://api.getsly.ai/v1/settlement/config \
  -H "Authorization: Bearer pk_live_..." \
  -d '{
    "x402FeePercentage": 0.025,
    "settlementSchedule": "daily"
  }'

​

When settlement matters

• Payouts to merchants — cadence affects their cash flow; schedule matters
• High-volume x402 — batching many tiny payments reduces rail fees
• Compliance — holdback reserves for chargebacks / refunds
• Accounting close — reconciliation reports feed your GL
• Regulatory reporting — settlement timing feeds transaction monitoring

​

When it doesn’t

• Same-currency internal transfers — happen instantly regardless of config
• Sandbox — most settlement happens mock-instantly for development speed
• Stablecoin-only integrations — on-chain settlement is the rail; no off-chain batching

​

Endpoints (section-wide)