Rates

What is a Rate?

A rate is a firm FX quote that guarantees an exchange rate for converting NGN to USDC/USDT. Each rate has:

Exchange Rate: NGN → USD/USDC/USDT conversion ratio
TTL (Time-to-Live): ~30-minute validity window
Rate ID: Unique identifier for binding to onramps
Minimum Deposit: Per-chain minimum amounts

New rates are generated approximately every 10 minutes. Rates expire ~30 minutes after creation.

Rate Properties

Property	Description	Example
`rate_id`	Unique identifier	`rate_8x7k2mq9p`
`from`	Source currency	`NGN`
`to`	Destination currency	`USDC`, `USDT`, `USD`
`rate`	Conversion rate (from → to)	`1545.50` (1 USDC = 1545.50 NGN)
`inverse_rate`	Inverse rate (to → from)	`0.000647` (1 NGN = 0.000647 USDC)
`fee_bps`	Fee in basis points	`50` (0.5%)
`min_deposit_ngn`	Minimum NGN amount per chain	`1500.00`
`created_at`	When rate was generated	`2026-01-14T15:05:00Z`
`expires_at`	When rate becomes invalid	`2026-01-14T15:35:00Z`

Getting Rates

Request current exchange rates using GET /v1/rates:

curl --request GET \
  --url 'https://api.daya.xyz/v1/rates?from=NGN&to=USDC' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response:

{
  "rate_id": "rate_8x7k2mq9p",
  "from": "NGN",
  "to": "USDC",
  "rate": 1545.50,
  "inverse_rate": 0.000647,
  "fee_bps": 50,
  "min_deposit_ngn": 1500.00,
  "created_at": "2026-01-14T15:05:00Z",
  "expires_at": "2026-01-14T15:35:00Z"
}

See Get Rates API for full details.

Query Parameters

Parameter	Required	Description	Allowed Values
`from`	✅ Yes	Source currency	`NGN`
`to`	❌ No	Destination currency (defaults to `USDC`)	`USDC`, `USDT`, `USD`

USD is treated as equivalent to USDC/USDT in v0.1. Depeg scenarios are not handled.

Rate Validity

Rates expire approximately 30 minutes after creation. Timeline:

Always check expires_at before using a rate_id to create an onramp. Using an expired rate will result in an error.

Rate Generation Schedule

New rates are generated approximately every 10 minutes:

Time	Rate ID	Valid Until
15:05	`rate_abc`	15:35
15:15	`rate_def`	15:45
15:25	`rate_ghi`	15:55
15:35	`rate_jkl`	16:05

This ensures continuous availability of valid rates.

Rate Semantics by Onramp Type

Throwaway Onramps
Permanent Onramps

Locked to rate_id at creation timeWhen you create a throwaway onramp:

You specify a rate_id
Onramp is bound to that rate
Deposits within rate validity execute at that rate
Deposits after rate expiry are FLAGGED

Guarantee: Rate is firm. No slippage within validity window.Example:

rate_id: rate_abc
rate: 1545.50 NGN/USDC
expires_at: 15:35

- Deposit at 15:20 → Uses 1545.50 ✅
- Deposit at 15:40 → FLAGGED ❌

Uses current rate at settlement timeWhen you create a permanent onramp:

You specify a rate_id (for informational purposes)
Onramp is not bound to that rate
Each deposit uses latest rate snapshot at execution time

Note: Subject to current market rate. Daya’s spread is applied.Example:

Onramp created with rate_abc (1545.50)

- Deposit 1 at 15:20 → Uses rate_abc (1545.50)
- Deposit 2 at 16:00 → Uses rate_xyz (1550.00)

Minimum Deposits

Each rate includes min_deposit_ngn, which specifies the minimum NGN amount for the destination chain.

Chain	Min Deposit NGN	Approx USD
BASE	1,500	~$1.00
Ethereum	1,500	~$1.00
Polygon	1,500	~$1.00

Minimum deposits are designed to cover on-chain gas fees. Deposits below minimum are rejected with status FAILED.

Rate Calculation

The rate includes Daya’s spread (fee):

Displayed Rate = Market Rate × (1 - fee_bps / 10000)

Example:

Market rate: 1550 NGN/USDC
Fee: 50 bps (0.5%)
Displayed rate: 1550 × (1 - 0.005) = 1545.50 NGN/USDC

The fee is already included in the displayed rate. Merchants do not need to calculate it separately.

Handling Rate Expiry

Request rate before onramp creation

Always call GET /v1/rates immediately before creating an onramp.

Check expires_at

Ensure expires_at is at least 25 minutes in the future (for throwaway onramps with 25-min TTL).

Show expiry to users

Display a countdown timer so users know they must complete the transfer quickly.

Handle expired rate errors

If POST /v1/onramp returns rate_expired, request a fresh rate and retry.

Edge Cases

No valid rate available

Scenario: FX venue is temporarily unavailableAPI Response:

{
  "error": {
    "code": "rate_unavailable",
    "message": "No valid exchange rates available at this time",
    "details": "Please try again in a few minutes"
  }
}

Merchant action: Retry after a few minutes or notify users of temporary unavailability.

Rate expires during onramp creation

Scenario: Rate expires between GET /v1/rates and POST /v1/onrampAPI Response:

{
  "error": {
    "code": "rate_expired",
    "message": "The specified rate_id has expired",
    "details": "Request a new rate via GET /v1/rates"
  }
}

Merchant action: Request a fresh rate and retry onramp creation.

Deposit after rate expiry

Scenario: User transfers NGN after rate expiresResult: Deposit status → FLAGGEDReason: "Deposit received after rate expiry"Resolution: Manual operations review required.

Rate Immutability

Once a rate is published:

It cannot be modified
It cannot be extended beyond expires_at
It cannot be retroactively applied

This ensures onramps have predictable FX behavior.

Best Practices

Cache rates with TTL

Cache rates client-side with respect to expires_at. Refresh when approaching expiry.

const rateCache = {
  rate: null,
  expiresAt: null
};

async function getValidRate() {
  if (!rateCache.rate || new Date() > rateCache.expiresAt) {
    const response = await fetch('/v1/rates?from=NGN');
    rateCache.rate = await response.json();
    rateCache.expiresAt = new Date(rateCache.rate.expires_at);
  }
  return rateCache.rate;
}

Show countdown timers

Display remaining validity time to users:

function getSecondsRemaining(expiresAt) {
  return Math.max(0, (new Date(expiresAt) - new Date()) / 1000);
}

Handle rate unavailability gracefully

If no rate is available, show a friendly message instead of cryptic errors.

Log rate usage

Log which rate_id was used for each onramp creation for troubleshooting.

Testing Rates

In sandbox, rates are simulated but follow the same behavior as production:

Generated every ~10 minutes
Expire after ~30 minutes
Same API surface

You can test:

Rate expiry handling
Onramp creation with expired rates
Deposit after rate expiry scenarios

Next Steps

Get Rates API

Full API reference for rates endpoint

Create Onramp

Use rates to create onramps

Edge Cases

Handle rate expiry and failure scenarios

Getting Started

Core Concepts

Onramp Types

Lifecycle & Statuses

Limits & Risk

What is a Rate?

Rate Properties

Getting Rates

Query Parameters

Rate Validity

Rate Generation Schedule

Rate Semantics by Onramp Type

Minimum Deposits

Rate Calculation

Handling Rate Expiry

Edge Cases

Rate Immutability

Best Practices

Testing Rates

Next Steps

Get Rates API

Create Onramp

Edge Cases

Getting Started

Core Concepts

Onramp Types

Lifecycle & Statuses

Limits & Risk

​What is a Rate?

​Rate Properties

​Getting Rates

​Query Parameters

​Rate Validity

​Rate Generation Schedule

​Rate Semantics by Onramp Type

​Minimum Deposits

​Rate Calculation

​Handling Rate Expiry

​Edge Cases

​Rate Immutability

​Best Practices

​Testing Rates

​Next Steps

Get Rates API

Create Onramp

Edge Cases

What is a Rate?

Rate Properties

Getting Rates

Query Parameters

Rate Validity

Rate Generation Schedule

Rate Semantics by Onramp Type

Minimum Deposits

Rate Calculation

Handling Rate Expiry

Edge Cases

Rate Immutability

Best Practices

Testing Rates

Next Steps