# Quote request

Request a quote with a locked price and a unique `quoteId`. The quote is valid for **3 minutes** (`expiresAt`). Unique identifier for this quote. Use this when creating a ramp transaction via the Ramps Request payload to lock the quote in.
Prices are subject to change based on market volatility and network congestion. Once expired, a new quote must be requested.

Endpoint: GET /eapi/v0/quote
Version: 0 BETA
Security: HMACAuth

## Security:

  - `HMACAuth` (unknown)
    apiKey in header Authorization

## Query parameters:

  - `identityReference` (string, required)
    A unique customer identifier provided by you. This field is required and must be unique for each customer. Please ensure you consistently reuse the same identityReference for repeat interactions with the same customer, allowing us to reliably recognize and associate their identity.

  - `fiat` (string, required)
    The desired fiat currency. Must be formatted as an ISO 4217 code.

  - `crypto` (string, required)
    The desired crypto token.

  - `method` (string, required)
    The payment method.

| Available payments |
|-------------|
|debit-credit-card|
|apple-pay|
|sepa-bank-transfer|
|gbp-bank-transfer|
|ach-bank-transfer|
|upi|
|zar-bank-transfer|
|interac-bank-transfer|
|ideal-bank-transfer|
|google-pay|
|payid-bank-transfer|
|poli-bank-transfer|
|try-bank-transfer|
|wire-transfer|
|spei|
|pse|
|khipu|
|io-ar-bank-transfer|
|aud-bank-transfer|
|open-banking|
|euro-open-banking|
|usd-bank-transfer|
|paypal|
|klarna-paynow|

  - `blockchain` (string, required)
    The blockchain for the crypto currency e.g. TRON or ETH.

  - `transactionType` (string, required)
    The type of transaction.

  - `fiatAmount` (number)
    **Required without cryptoAmount**
The amount in fiat currency to convert.
Amount in fiat minor precision (typically 2 decimals).
This locks the fiat amount; the crypto amount will be computed and rounded to the configured crypto scale.
Note: due to differing decimal scales and rounding rules, converting fiat→crypto and then crypto→fiat may not return the exact original number.

  - `cryptoAmount` (number)
    **Required without fiatAmount**
Amount in crypto precision (token-dependent, e.g., 6–8 decimals).
This locks the crypto amount; the fiat amount will be computed and rounded to the fiat scale.
Note: small differences vs the reverse path are expected from precision/rounding.

## Response 200:

  - `200` (unknown)
    Quote response with a unique `quoteId` and an `expiresAt` timestamp. The quote is valid for 3 minutes.

## Response 200 fields (application/json):

  - `quoteId` (string, required)
    Unique identifier for this quote. Use this when creating a ramp transaction via the Ramps Request payload to lock the quote in.
    Example: 6e9174edd370ffe6331aeda7a6d75592

  - `identityReference` (string, required)
    A unique customer identifier provided by the partner. This field is required and must be unique for each customer.
**Important**: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.
**Format Requirements**:
- Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
- Must be between 1 and 255 characters
- Case-sensitive

**Best Practices**:
- Use a consistent format across your system
- Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
- Do not include personally identifiable information (PII) in the reference
- Store the mapping between your internal customer ID and this reference securely
    Example: c-13344

  - `source` (object, required)

  - `source.fiat` (object, required)

  - `source.fiat.id` (string, required)
    The fiat currency.
    Example: AUD

  - `source.fiat.method` (string, required)
    The payment method.
    Example: payid-bank-transfer

  - `source.amount` (string, required)
    The amount of fiat in.
    Example: 24.50

  - `target` (object, required)

  - `target.crypto` (object, required)

  - `target.crypto.id` (string, required)
    The crypto token.
    Example: ETH

  - `target.crypto.blockchain` (string, required)
    The blockchain that is associated with the crypto token.
    Example: ETH

  - `target.amount` (string, required)
    The total amount of crypto out.
    Example: 0.007259

  - `processingFee` (string, required)
    The processing fee associated with the quote.
    Example: 0.00

  - `networkFee` (string, required)
    The network fee (gas fee) associated with the quote.
    Example: 0.00

  - `marketRate` (object, required)
    Current market rates for crypto and forex conversions.

  - `marketRate.crypto` (object, required)
    Map of fiat currency codes to crypto market rates.
**Format**: Each property is a fiat currency code, and the value is the amount of that fiat currency equal to 1 unit of the crypto.
    Example: {"USD":"2342.218527689999974","AUD":"3297.796842616966163"}

  - `marketRate.forex` (object, required)
    Foreign exchange rates relative to the reference currency.
    Example: {"reference":"USD","AUD":"1.4079800"}

  - `marketRate.forex.reference` (string, required)
    Reference/base currency used for all forex conversion values.
    Example: USD

  - `expiresAt` (string, required)
    The expiry timestamp of the quote. The quote is valid for 3 minutes from creation.
    Example: 2026-04-10 04:50:36

## Response 400:

  - `400` (unknown)
    Bad request due to invalid input.
**Common Causes**:
- Malformed JSON in request body
- Invalid data types
- Missing required fields
- Invalid request structure

## Response 400 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Bad Request

  - `code` (integer)
    HTTP status code
    Example: 400

  - `traceId` (string)
    Unique identifier for this error instance. Use this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 401:

  - `401` (unknown)
    Authentication failed or missing credentials.
**Common Causes**:
- Missing Authorization header
- Invalid API key
- Expired or invalid HMAC signature
- Incorrect timestamp (must be within 5 minutes of server time)

## Response 401 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Unauthenticated.

  - `code` (integer)
    HTTP status code
    Example: 401

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 404:

  - `404` (unknown)
    The requested resource was not found.
**Common Causes**:
- Invalid ramp ID
- Invalid identity reference
- Resource has been deleted
- Incorrect endpoint URL

## Response 404 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Not Found

  - `code` (integer)
    Error code (may be HTTP status or custom code)
    Example: 500100

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 422:

  - `422` (unknown)
    Validation error - request is well-formed but contains invalid data.
**Common Causes**:
- Field validation failures
- Business rule violations
- Invalid field combinations
- Out of range values

## Response 422 fields (application/json):

  - `message` (string)
    Summary of validation errors
    Example: The given data was invalid.

  - `errors` (object)
    Map of field names to error messages.
**Format**: Each key is a field name, value is an array of error messages for that field.
    Example: {"email":["The email field is required."],"fiatAmount":["The fiat amount must be at least 10."]}

  - `code` (integer)
    HTTP status code
    Example: 422

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 429:

  - `429` (unknown)
    Rate limit exceeded.
**Rate Limits**:
- General API: 100 requests per minute
- Price endpoint: 60 requests per minute

**Action**: Wait for the duration specified in `Retry-After` header before retrying.

## Response 429 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Too Many Requests. Please try again later.

  - `code` (integer)
    HTTP status code
    Example: 429

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 429 headers (application/json):

  - `Retry-After` (integer)
    Number of seconds to wait before retrying.

**Important**: Always respect this header to avoid further rate limiting.
    Example: 60

## Response 500:

  - `500` (unknown)
    Unexpected server error.
**Action**:
- Retry with exponential backoff (up to 3 attempts)
- If error persists, contact support with the traceId

**Note**: This is a temporary issue on our side, not a problem with your request.

## Response 500 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Server Error

  - `code` (integer)
    HTTP status code
    Example: 500

  - `traceId` (string)
    Unique identifier for this error instance. **Important**: Include this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 200 examples:

  - `On-ramp quote with fiat amount locked` (unknown)
    Customer wants to spend exactly 24.50 AUD to buy ETH

  - `On-ramp quote with crypto amount locked` (unknown)
    Customer wants to receive exactly 0.01 ETH

  - `Off-ramp quote with crypto amount locked` (unknown)
    Customer wants to sell exactly 100 USDT for AUD