Skip to content
/
Ramps enable Fiat to Cryp...

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

Request

Enables conversion between fiat and cryptocurrency in both directions.

Security
HMACAuth
Bodyapplication/jsonrequired
One of:
One of:
subPartnerIdstring, >= 1

Your defined ID for associating an order with. You may use this to differentiate between your customers.

Example:"2125"
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$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"
sourceobjectrequired
targetobjectrequired
fiatAmountstringrequired

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"
curl -i -X POST \
  https://docs.banxa.com/_mock/products/native-api/openapi/eapi/v0/ramps \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityReference": "customer-12345",
    "subPartnerId": "partner-app-1",
    "source": {
      "fiat": {
        "id": "AUD",
        "method": "payid-bank-transfer"
      }
    },
    "target": {
      "crypto": {
        "id": "USDT",
        "blockchain": "TRON",
        "walletAddress": "TYDzsYUEpvnYmQk4zGP9sWWcTEd2MiAtW6",
        "walletAddressMemo": "39730"
      }
    },
    "fiatAmount": "100.00"
  }'

Responses

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.

Bodyapplication/json
One of:
idstringrequired

The ramp ID.

Example:"4002"
subPartnerIdstringrequired

Your defined ID for associating an order with. You may use this to differentiate between your customers.

Example:"2125"
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$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"
statusstringrequired
StatusDescription
INITIALIZEDThe request has been accepted and is queued for processing.
AWAITING_FUNDSThe order is ready; awaiting receipt of funds at the specified wallet address.
FUNDS_RECEIVEDFunds have been successfully received at the destination wallet address.
UNDER_REVIEWThe order is undergoing compliance and security review.
COMPLETEDThe order is finalized: funds have been secured and fiat disbursed to the customer's method.
CANCELLEDThe order has been cancelled and will not proceed.
REFUNDEDThe amount has been returned to the customer's wallet address.
Enum:"INITIALIZED""AWAITING_FUNDS""PAYMENT_SUBMITTED""FUNDS_RECEIVED""UNDER_REVIEW""CANCELLED""REFUNDED""COMPLETED"
Example:"INITIALIZED"
sourceobjectrequired
targetobjectrequired
sourceDepositInstructionsobjectrequired
receiptobjectrequired
createdAtstring, (date-time)required

The UTC date time of creation.

Example:"2023-05-05T19:53:08.320Z"
completedAtstring or null, (date-time)required

The UTC date time of the completion. Null if not yet completed.

Example:"2023-06-05T19:53:08.320Z"
Response
Response for an on-ramp transaction. Customer needs to make payment to the provided instructions.
{
  "id": "b7f1ffbb2f1bd7a5e2ba152b4049d234",
  "subPartnerId": "partner-app-1",
  "identityReference": "customer-12345",
  "status": "INITIALIZED",
  "source": {
    "fiat": { … },
    "amount": "100.00"
  },
  "target": {
    "crypto": { … },
    "amount": "95.50"
  },
  "sourceDepositInstructions": {
    "recipientEmail": "[email protected]",
    "depositReference": "BNX-12345678"
  },
  "receipt": {
    "targetTransactionHash": null,
    "gatewayFee": "2.50",
    "networkFee": "2.00",
    "sourceAmount": "100.00",
    "targetAmount": "95.50"
  },
  "createdAt": "2023-06-05T19:53:08.320Z",
  "completedAt": null
}
© Banxa 2026