API reference

Markets and rates

List open markets and read live exchange rates and limits before every transaction.

A market is a country Deripay moves money in. Read the open markets from the API rather than hardcoding them: a market can open or close without a change on your side, and what you must ask the customer for differs by market.

List markets

http

GET /api/v2/markets

Any valid key.

json

{
  "success": true,
  "data": {
    "markets": [
      {
        "country": "KE",
        "name": "Kenya",
        "currency": "KES",
        "dialing_code": "254",
        "national_number_length": 9,
        "deposit_limits": { "min": 10, "max": 250000 },
        "operators": [{ "code": "mpesa", "name": "M-Pesa" }],
        "requires_operator": false
      },
      {
        "country": "UG",
        "name": "Uganda",
        "currency": "UGX",
        "dialing_code": "256",
        "national_number_length": 9,
        "deposit_limits": { "min": 5000, "max": 5000000 },
        "operators": [
          { "code": "airtel", "name": "Airtel Money" },
          { "code": "mtn", "name": "MTN Mobile Money" }
        ],
        "requires_operator": true
      }
    ]
  }
}

Values above are illustrative.

Field	Description
`country`	Two-letter country code. Send it as `country` on deposits, withdrawals and `/rates`.
`name`	Market name to show.
`currency`	Local currency (`KES`, `TZS`, `UGX`). Every local amount in this market is a whole number of it.
`dialing_code`	Country calling code without `+`.
`national_number_length`	Digits after the dialing code. A number of the wrong length is rejected for this market.
`deposit_limits`	The provider's own floor and ceiling, in whole local units. The window that applies right now comes from `/rates`.
`operators`	Mobile money networks: `code` to send, `name` to show.
`requires_operator`	`true` when the customer must choose a network. Send its `code` as `operator`.

Operator codes in use today:

Market	Operator codes
`KE`	`mpesa` (you can omit `operator` in Kenya)
`TZ`	`airtel`, `halopesa`, `tigo`, `vodafone`
`UG`	`airtel`, `mtn`

Use the codes exactly as returned. In Tanzania the Vodafone M-Pesa code is vodafone. When a market has one operator and does not require a choice, Deripay picks it for you.

Get rates and limits

http

GET /api/v2/rates?country=UG

Any valid key. Without country the answer is for Kenya. A country that is not open returns 400 MARKET_NOT_AVAILABLE.

json

{
  "success": true,
  "data": {
    "country": "UG",
    "currency": "UGX",
    "deposit_rate": 3900,
    "withdraw_rate": 3550,
    "deposits_available": true,
    "deposit_limits": { "min": 20000, "max": 2000000 },
    "withdraw_limits_usd": { "min": 5, "max": 500 },
    "effective_date": "2026-11-03",
    "fetched_at": "2026-11-03T08:00:00Z"
  }
}

Values above are illustrative.

Field	Description
`country`	The market.
`currency`	Local currency for this market. Label amounts with it, never with `KES` outside Kenya.
`deposit_rate`	Local units per USD used to convert a deposit. The customer's Deriv credit is about `amount / deposit_rate` USD.
`withdraw_rate`	Local units per USD used to estimate a withdrawal payout. The payout is about `amount_usd * withdraw_rate`.
`deposits_available`	`false` when deposits in this market are paused. Disable your deposit button.
`deposit_limits`	`min` and `max` for a deposit right now, in whole local units.
`withdraw_limits_usd`	`min` and `max` for a withdrawal right now, in USD.
`effective_date`	Business date of the stored rate.
`fetched_at`	When the rate was fetched.

Rates and limits change during the day. Fetch them when you open the deposit or withdrawal form and again before you retry. The server checks every amount, so a stale limit gives you 400 AMOUNT_OUT_OF_RANGE instead of a bad transaction.

Whole units

Every local mobile money rail settles in whole units. A deposit amount must be an integer: 1000 KES, 500000 UGX. A value such as 1000.5 fails with 400 INVALID_REQUEST. Reject decimals in your form instead of rounding them.

Withdrawal amount_usd is in dollars and can have up to two decimals, for example 12.5.

Phone numbers

Collect a number from the market's own country. Deripay accepts local (0712345678), national (712345678) and international (254712345678, +254 712 345 678) forms and strips spaces and symbols. A number that does not fit the market fails with 400 INVALID_PHONE_NUMBER.

Most markets cannot confirm the recipient's name before money is sent. Read the number back to the customer before a withdrawal.

← Connections Deposits →