---
title: "Create a quote"
method: POST
path: "/quote"
tags: ["Quote"]
---

# Create a quote

`POST /quote`

Create a quote for a given currency

## Request body

- CreateQuote
  - `amount` number, required — The amount in the target currency in its lowest denomination. e.g '500000' for 5000.00 NGN
  - `sourceCurrency` 'BTCSAT' | 'NGNKOBO' | 'KESCENT' | 'ZARCENT', string, required — The source currency for the quote
  - `targetCurrency` 'NGNKOBO' | 'KESCENT' | 'ZARCENT' | 'BTCSAT', string, required — The local currency to convert the source currency to
  - `paymentMethod` 'LIGHTNING' | 'BANKTRANSFER', string, required — The payment method for the quote
  - `paymentCurrency` 'NGNKOBO' | 'BTCSAT' | 'KESCENT' | 'ZARCENT', string, required — Currency the amount is denominated in. Must be either sourceCurrency or targetCurrency. Determines what the 'amount' field represents. Example: if buying BTC with NGN and paymentCurrency is 'NGNKOBO', amount is in Naira; if 'BTCSAT', amount is in Bitcoin.
  - `autopayout` boolean
  - `beneficiary` union
    - object
      - `bankAccountNumber` string, required — The bank account number of the beneficiary
      - `bankAccountName` string, required — The name of the beneficiary
      - `bankCode` string, required — The bank code of the beneficiary
      - `bankName` string, required — The name of the bank of the beneficiary
    - object
      - `identifierType` 'paytophone' | 'paytobill', required — The type of identifier to use for the beneficiary
      - `identifiers` object, required
        - `phoneNumber` string — The phone number of the beneficiary if the identifierType is paytophone
        - `paybillNumber` string — The paybill number of the beneficiary if the identifierType is paytobill
        - `accountNumber` string — The account number of the beneficiary if the identifierType is paytobill
    - object
      - `name` string, required — The name of the beneficiary
      - `bankName` string, required — The name of the bank of the beneficiary
      - `bankAccountNumber` string, required — The bank account number of the beneficiary
    - object
      - `lnInvoice` string — Lightning Network invoice for Bitcoin payout (required when autopayout is true)
      - `lnAddress` string — Lightning address for Bitcoin payout (alternative to lnInvoice)
      - `onChainAddress` string — Bitcoin on-chain address for payout (alternative to lnInvoice)

## Response `200`

Quote response

- object
  - `status` string, string
  - `data` Quote
    - `id` string, uuid
    - `exchangeRate` number — The exchange rate of source currency to target currency for the quote. e.g 1 BTC = 5000000.23 NGN
    - `usdToTargetCurrencyRate` number — The USD to target currency rate for the quote
    - `sourceCurrency` 'BTCSAT' | 'NGNKOBO' | 'KESCENT' | 'ZARCENT', string — The source currency for the quote
    - `targetCurrency` 'NGNKOBO' | 'KESCENT' | 'ZARCENT', string — The target currency for the quote
    - `transactionFeesInSourceCurrency` number — The transaction fees in the source currency in its lowest denomination
    - `transactionFeesInTargetCurrency` string, string — The transaction fees in the target currency in its lowest denomination
    - `amountInSourceCurrency` number — The amount in the source currency in its lowest denomination
    - `amountInTargetCurrency` string, string — The amount in the target currency in its lowest denomination
    - `paymentMethod` 'LIGHTNING', string
    - `expiry` string, date-time
    - `isValid` boolean
    - `invoice` string, string — The lightning invoice to pay for the quote
    - `hash` string, string — The payment hash for the lightning invoice attached to the quote
    - `totalAmountInSourceCurrency` number — The total amount in the source currency in its lowest denomination
    - `customerInternalFee` number — An internal fee you can set to charge the customer. This fee is in the source currency in its lowest denomination
    - `createdAt` string, date-time — The date and time the quote was created
    - `updatedAt` string, date-time — The date and time the quote was last updated
    - `bankName` string, string — Bank name for NGN bank transfer (when paymentMethod is BANKTRANSFER)
    - `ngnBankAccountNumber` string, string — Bank account number for NGN payment (when paymentMethod is BANKTRANSFER)
    - `ngnAccountName` string, string — Account name for NGN payment (when paymentMethod is BANKTRANSFER)
    - `ngnBankCode` string, string — NIP bank code for NGN payment (when paymentMethod is BANKTRANSFER)
    - `orderId` string, string — Unique order identifier for tracking
    - `estimatedRoutingFee` number — Estimated routing fee for Lightning Network payments in satoshis

## Other responses

- `400` — Unexpected error

## Changes

- **2026-02-11** `123a05fa89e9` — 5 info
  - added the new `BANKTRANSFER` enum value to the request property `paymentMethod`
  - added the new `BTCSAT` enum value to the request property `targetCurrency`
  - added the new `KESCENT` enum value to the request property `sourceCurrency`
  - added the new `NGNKOBO` enum value to the request property `sourceCurrency`
  - …1 more
- **2026-01-16** `26b6661951c2` — 8 info
  - added the new `BTCSAT` enum value to the request property `paymentCurrency`
  - added `subschema #4: BTC Beneficiary` to the `beneficiary` request property `oneOf` list
  - added the optional property `data/bankName` to the response with the `200` status
  - added the optional property `data/estimatedRoutingFee` to the response with the `200` status
  - …4 more
- **2025-02-01** `6bb4d2ebd1b9` — 13 breaking, 1 warning, 15 info
  - the request property `amount` became required
  - the request property `paymentCurrency` became required
  - removed the enum value `BTC` of the request property `paymentCurrency`
  - removed the enum value `BTC` of the request property `sourceCurrency`
  - …25 more
- …earlier changes not shown

[Full history](https://skmtc.dev/stealthmoney/apis/mavapay-api/changes/quote/post.md)

---

[API](https://skmtc.dev/stealthmoney/apis/mavapay-api.md) · [All operations](https://skmtc.dev/stealthmoney/apis/mavapay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stealthmoney/apis/mavapay-api/revisions/d7762b61d268?raw)