Skip to main content

​
Overview

Rates and settlement define how value moves through the Daya API:
  • Rates determine how much stablecoin a deposit converts into
  • Settlement determines where the converted funds are delivered
These rules are deterministic and depend on the funding account type and settlement destination.

​
Rates

A rate is a firm FX quote used to convert between NGN and stablecoins. Each rate includes:
  • A fixed exchange rate
  • A side (BUY or SELL)
  • A defined validity window (TTL)
  • A unique rate_id for funding account settlement requests that need a firm quote

​
Buy vs Sell Rates

New rates are generated approximately every 10 minutes and expire about 30 minutes after creation.

​
Rate Properties (Conceptual)

Each rate defines the following attributes: Rates are immutable once published.

​
Rate Semantics by Funding Account Type

How a rate is applied depends on the funding account.

​
Temporary Funding Accounts (Firm Rates)

Temporary funding accounts are bound to a specific rate_id at creation when the API contract requires a quote.
  • Deposits received within the validity window execute at the bound rate
  • Deposits received after expiry do not settle automatically
  • No slippage occurs within the validity window
This includes:
  • Temporary NGN_VIRTUAL_ACCOUNT funding accounts that settle to INTERNAL_BALANCE
  • Temporary NGN_VIRTUAL_ACCOUNT funding accounts that settle to NGN_BALANCE
  • Temporary NGN_VIRTUAL_ACCOUNT funding accounts that settle through ONCHAIN
  • Temporary CRYPTO_ADDRESS funding accounts that settle through NGN_PAYOUT
All temporary NGN virtual accounts currently require a BUY rate_id, including NGN_BALANCE. Retained-NGN settlement does not convert the deposit, but the temporary-account creation contract still validates and binds the BUY rate. Permanent NGN_BALANCE accounts do not require a rate.
This provides price certainty for time-sensitive or one-time transactions.

​
Permanent NGN Funding Accounts (Floating Rates)

Permanent NGN funding accounts are not bound to a specific rate.
  • Each deposit uses the current rate at the time of execution
  • Rates may differ between deposits on the same funding account
  • Subject to market movement and spread
This is best suited for recurring or long-lived deposit flows.

​
Merchant NGN Funding Accounts

The permanent NGN account returned by GET /v1/merchant/funding has a merchant-level settlement preference:
  • USD_BALANCE uses the current floating rate for each deposit and credits withdrawal_balance_usd. This is the default.
  • NGN_BALANCE skips FX and credits the received Naira directly to withdrawal_balance_ngn.
Use PATCH /v1/merchant/funding/settlement-destination to opt into retained NGN or return to automatic USD conversion. The setting applies to future merchant funding deposits and does not change existing balances.

​
Customer NGN Balances

Permanent customer funding accounts can use CUSTOMER_NGN_BALANCE:
  • NGN virtual-account deposits remain NGN and credit that customer’s balance without FX conversion.
  • Confirmed USDC and USDT deposits use the applicable stablecoin-to-NGN rate, then credit that customer’s NGN balance.
Read the result with GET /v1/customers/{id}/balances. This balance is separate from the merchant’s withdrawal_balance_ngn.

​
Rate Expiry Behavior

If a deposit arrives after a bound rate expires:
  • The deposit is FLAGGED
  • No FX or settlement occurs automatically
  • Manual review is required
Rates cannot be extended, reused, or retroactively applied.

​
Settlement

Settlement defines where converted stablecoins are sent after FX conversion. Settlement behavior is configured on the funding account.

​
Settlement Modes

​
On-chain (ONCHAIN)

Converted stablecoins are sent to a blockchain address.
  • Settlement occurs after FX conversion
  • Subject to risk checks
  • Finalized once the on-chain transaction confirms
Used for direct wallet settlement and real-time delivery.

​
Internal balance (INTERNAL_BALANCE)

Converted funds are credited to the merchant’s Daya balance.
  • No immediate on-chain transaction
  • Funds can be withdrawn later
  • Useful for aggregation and batch withdrawals

​
NGN Payout (NGN_PAYOUT)

For crypto funding account deposits — converted funds are paid out as NGN to a Nigerian bank account.
  • Temporary crypto funding accounts require a rate_id (SELL rate) and destination_bank
  • Settlement occurs after crypto deposit is confirmed and FX conversion is executed

​
Guarantees & Invariants

Daya enforces the following guarantees:
  • FX conversion and settlement are atomic
  • Partial execution is not possible
  • Rates are firm for temporary rate-locked funding accounts
  • Settlement behavior is immutable per temporary funding account (permanent funding accounts can update settlement)

​
What Rates and Settlement Do Not Guarantee

  • Rates do not guarantee settlement if deposits arrive late
  • Settlement does not occur if deposits are flagged or failed
  • Permanent funding accounts do not guarantee a fixed price

​
Next Steps

Funding Accounts

See how receive-money settlement is configured

Deposits

Understand the deposit lifecycle

Rates API

View the API reference