# Ramps enable Fiat to Crypto and Crypto to fiat on and off ramp.

Enables conversion between fiat and cryptocurrency in both directions.

Endpoint: POST /eapi/v0/ramps
Version: 0 BETA
Security: HMACAuth

## Security:

  - `HMACAuth` (unknown)
    apiKey in header Authorization

## Request fields (application/json):

  - `subPartnerId` (string)
    Your defined ID for associating an order with. You may use this to differentiate between your customers.
    Example: 2125

  - `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 to be transferred. Must be formatted as an ISO 4217 code.
    Example: AUD

  - `source.fiat.method` (string, required)
    | Available payments |
|  --- |
| interac-bank-transfer |
| payid-bank-transfer |
| sepa-bank-transfer |
    Example: payid-bank-transfer

  - `source.fiat.tosAccepted` (boolean)
    Indicates whether the customer has accepted the Terms of Service. Required for ach-bank-transfer method if the customer has not previously signed the terms of service agreement.
    Example: true

  - `target` (object, required)

  - `target.crypto` (object, required)

  - `target.crypto.id` (string, required)
    The crypto token to be received.
    Example: XRP

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

  - `target.crypto.walletAddress` (string, required)
    The wallet address Banxa will use to transfer the crypto.
    Example: rp93JdjfXxPYVjo5E7qF4G6tRbBeweUz9K

  - `target.crypto.walletAddressMemo` (string)
    The wallet address memo associated with the wallet address.
    Example: 39730

  - `fiatAmount` (string, required)
    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.
    Example: 100

  - `cryptoAmount` (string, required)
    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.
    Example: 100

  - `subPartnerId` (string)
    Your defined ID for associating an order with. You may use this to differentiate between your customers.
    Example: 2125

  - `quoteId` (string, required)
    The unique identifier of a previously obtained price quote.
    Example: 6e9174edd370ffe6331aeda7a6d75592

  - `walletAddress` (string, required)
    The wallet address to use for the transaction.
    Example: 0xc292474673cf1a96a96e8c56ec4f45ecf2e0b448

  - `walletAddressMemo` (string | null)
    The wallet address memo associated with the wallet address.
    Example: null

## Request examples:

  - `On-Ramp with fiat amount (Buy crypto)` (unknown)
    Customer wants to buy USDT on TRON network using AUD via PayID. Fiat amount is locked at 100 AUD.

  - `On-Ramp with crypto amount (Buy exact crypto)` (unknown)
    Customer wants to buy exactly 100 USDT using SEPA. Fiat amount will be calculated.

  - `Off-Ramp with crypto amount (Sell crypto)` (unknown)
    Customer wants to sell 100 USDT for AUD. Crypto amount is locked.

  - `Off-Ramp with fiat amount (Receive exact fiat)` (unknown)
    Customer wants to receive exactly 100 AUD. Crypto amount will be calculated.

  - `Ramp using a quote ID` (unknown)
    Create a ramp transaction using a previously obtained quote ID. Source, target, and amount details are inferred from the quote.

  - `Off-Ramp with ACH bank transfer` (unknown)
    Customer wants to sell crypto and receive USD via ACH. Includes tosAccepted for ACH terms of service.

## Response 201:

  - `201` (unknown)
    Successful ramp response.
**Next Steps**:
- **On-Ramp**: Display payment instructions to customer (sourceDepositInstructions)
- **Off-Ramp**: Display crypto deposit address to customer (sourceDepositInstructions)
- Monitor status via webhooks or GET endpoint

**Important**: The response type (OnRamp vs OffRamp) matches the request type.

## Response 201 fields (application/json):

  - `id` (string, required)
    The ramp ID.
    Example: 4002

  - `subPartnerId` (string, required)
    Your defined ID for associating an order with. You may use this to differentiate between your customers.
    Example: 2125

  - `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

  - `status` (string, required)
    | Status | Description |
|  --- | --- |
| INITIALIZED | The request has been accepted and is queued for processing. |
| AWAITING_FUNDS | The order is ready; awaiting receipt of funds at the specified wallet address. |
| FUNDS_RECEIVED | Funds have been successfully received at the destination wallet address. |
| UNDER_REVIEW | The order is undergoing compliance and security review. |
| COMPLETED | The order is finalized: funds have been secured and fiat disbursed to the customer's method. |
| CANCELLED | The order has been cancelled and will not proceed. |
| REFUNDED | The amount has been returned to the customer's wallet address. |
    Enum: "INITIALIZED", "AWAITING_FUNDS", "PAYMENT_SUBMITTED", "FUNDS_RECEIVED", "UNDER_REVIEW", "CANCELLED", "REFUNDED", "COMPLETED"

  - `source` (object, required)

  - `source.crypto` (object, required)

  - `source.crypto.id` (string, required)
    The crypto token to be transferred.
    Example: USDT

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

  - `source.crypto.walletAddress` (string, required)
    The wallet address that will be used to send the crypto. This will also be the wallet address used for refunds if a refund is necessary.
    Example: 0x46B2E9701FE4F6C0A23533D196DbBE7EfEeDea4F

  - `source.crypto.walletAddressMemo` (string)
    The wallet address memo associated with the wallet address.
    Example: 1234

  - `source.amount` (string, required)
    The amount of crypto to be transferred
    Example: 105

  - `target` (object, required)

  - `target.fiat` (object, required)

  - `target.fiat.id` (string, required)
    The fiat currency to be received. Must be formatted as an ISO 4217 code.
    Example: USD

  - `target.fiat.method` (string, required)
    The payment method used for the ramp.
    Example: payid-bank-transfer

  - `target.amount` (string, required)
    The amount of fiat to be received.
    Example: 100.5

  - `sourceDepositInstructions` (object, required)

  - `sourceDepositInstructions.walletAddress` (string, required)
    The Banxa deposit wallet address.
    Example: 0x46B2E9701FE4F6C0A23533D196DbBE7EfEeDea4F

  - `sourceDepositInstructions.walletAddressMemo` (string, required)
    The wallet address memo assoicated with the Banxa deposit wallet address.
    Example: 1684

  - `receipt` (object, required)

  - `receipt.sourceTransactionHash` (string | null, required)
    The transaction hash of the crypto transfer. Null if not yet received.
    Example: 0x637f3f8c7b15a83657901ca9f9e0134f0b7dad09e09fbac8a637d026343f586e

  - `receipt.gatewayFee` (string, required)
    The fee charged by the payment processor.
    Example: 1.95

  - `receipt.networkFee` (string, required)
    The blockchain network fee required to process the transaction.
    Example: 1.95

  - `receipt.sourceAmount` (string, required)
    The amount of crypto transferred.
    Example: 100

  - `receipt.targetAmount` (string, required)
    The amount of fiat received.
    Example: 100

  - `createdAt` (string, required)
    The UTC date time of creation.
    Example: 2023-05-05T19:53:08.320Z

  - `completedAt` (string | null, required)
    The UTC date time of the completion. Null if not yet completed.
    Example: 2023-06-05T19:53:08.320Z

  - `status` (string, required)
    | Status | Description |
|  --- | --- |
| INITIALIZED | The request has been accepted and is queued for processing. |
| AWAITING_FUNDS | The order is ready; awaiting receipt of funds through the specified payment method. |
| FUNDS_RECEIVED | Funds have been successfully received via the requested payment method. |
| UNDER_REVIEW | The order is undergoing compliance and security review. |
| COMPLETED | The order is finalized: funds have been secured and crypto is disbursed to the customer's wallet address. |
| CANCELLED | The order has been cancelled and will not proceed. |
| REFUNDED | The order amount has been returned to the customer. |
    Enum: "INITIALIZED", "AWAITING_FUNDS", "PAYMENT_SUBMITTED", "FUNDS_RECEIVED", "UNDER_REVIEW", "CANCELLED", "REFUNDED", "COMPLETED"

  - `createdAt` (string, required)
    The UTC date time of the transaction creation.
    Example: 2023-05-05T19:53:08.320Z

  - `completedAt` (string | null, required)
    The UTC date time of the transaction completion. Null if not yet completed.
    Example: 2023-06-05T19:53:08.320Z

## 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 201 examples:

  - `On-Ramp Response` (unknown)
    Response for an on-ramp transaction. Customer needs to make payment to the provided instructions.

  - `Off-Ramp Response` (unknown)
    Response for an off-ramp transaction. Customer needs to send crypto to the provided address.