Skip to main content
POST
/
api
/
partner
/
v2
/
on-ramp
cURL
curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/on-ramp \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <partner-api-key>' \
  --data '{
  "quoteId": "<string>",
  "userId": "8374f327-38bd-4b0b-b8a7-2524599eb903",
  "fiatAmount": 10200,
  "cryptoAmount": 10200,
  "destinationWalletAddress": "0x4d2f3d8f83b6f2f8e0f3f4f3f3f3f3f3f3f3f3f3",
  "fiatCurrency": "MXN",
  "blockchainSymbol": "BASE",
  "tokenSymbol": "ETH",
  "premiumSpread": 0.01
}'
{
  "success": true,
  "data": {
    "id": "63f51f11-6869-47b0-a109-ddb50ef20efb",
    "userId": "8374f327-38bd-4b0b-b8a7-2524599eb903",
    "status": "PENDING_PAYMENT",
    "cryptoAmount": 2500,
    "fiatAmount": 50000,
    "crossFiatAmount": 123,
    "exchangeRate": 19.53964594161554,
    "tokenSymbol": "USDC",
    "blockchainSymbol": "POL",
    "fiatCurrency": "MXN",
    "premiumSpread": 0.01,
    "createdAt": "2025-05-14T10:00:00Z",
    "completedAt": "<string>",
    "destinationWalletAddress": "0x7796d4f304bd84171ee6730ad0f69c07a47e786d",
    "bankAccount": {
      "country": "MX",
      "accountIdentifier": "014680260346007120",
      "bankName": "Santander",
      "accountType": "SAVINGS",
      "isVerified": true,
      "documentIdentifier": "123abc",
      "documentType": "RNC",
      "iban": "DE89370400440532013000",
      "bic": "DEUTDEFF",
      "routingNumber": "021000021"
    }
  }
}
Creates an on-ramp transaction on behalf of a verified user. This enables the conversion of fiat to crypto and initiates the transfer to the target wallet.

​
🔐 Headers

HeaderDescription
partner-api-keyAPI key associated with your partner account. Required. See API Key Generation Guide.
This endpoint requires authentication using a valid partner-api-key.
For Staging Transaction Testing please use Mock Testing Guide

​
📥 Request Body

ParameterTypeRequiredDescription
userIdstring✅ID of the user on whose behalf the transaction is created.
The user’s identity must be verified first.
fiatAmountnumber🔘Amount of fiat to be converted. Required if cryptoAmount is not provided.
cryptoAmountnumber🔘Amount of crypto to be converted to fiat. Required if fiatAmount is not provided.
fiatCurrencystring✅Currency for the off-ramp transaction.
The user must have an account in this currency.
Accepted values follow the ISO 4217 format (e.g., MXN, DOP).
blockchainSymbolstring✅Identifier of the blockchain used for the conversion. Refer to our supported blockchain list for availability.
tokenSymbolstring✅Identifier of the token used for the conversion. Refer to our supported token list for availability.
premiumSpreadnumber🔘Additional percentage applied to the exchange rate. This amount is fully awarded to the partner.
destinationWalletAddressstring✅Wallet where the funds are gonna be awarded.

​
📨 Example Request

curl
curl --request POST \
     --url https://staging-api.capa.fi/api/partner/v2/on-ramp \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'partner-api-key: API-KEY' \
     --data '
{
  "fiatCurrency": "MXN",
  "blockchainSymbol": "POL",
  "tokenSymbol": "USDC",
  "userId": "d3127f5f-ff64-47f9-a9cc-ff603862eca6",
  "fiatAmount": 10000,
  "destinationWalletAddress": "0x4d2f3d8f83b6f2f8e0f3f4f3f3f3f3f3f3f3f3f3",
  "premiumSpread": 0.01
}
'

​
📤 Response Body

FieldTypeDescription
idstringUnique ID of the created transaction.
userIdstringUser ID associated with the transaction.
statusstringCurrent status of the transaction. Initially set to "PENDING".
cryptoAmountnumberAmount of cryptocurrency being converted.
fiatAmountnumberAmount of fiat currency received after conversion.
exchangeRatenumberExchange rate used for the crypto-to-fiat conversion.
tokenSymbolstringSymbol of the cryptocurrency used.
blockchainSymbolstringSymbol of the blockchain the cryptocurrency belongs to.
fiatCurrencystringCurrency code of the fiat currency received (e.g., "MXN").
createdAtstringISO timestamp indicating when the transaction was created.
completedAtstringISO timestamp indicating when the transaction was completed, or null if pending.
destinationWalletAddressstringWallet where the user will receive the funds.
bankAccountobjectInformation about the user’s bank account.
bankAccount .isVerifiedbooleanIndicates whether the account has been verified and linked to the user.
bankAccount .accountIdentifierstringUnique identifier of the account (CLABE for Mexico, Account Number for DO).
bankAccount .countrystringCountry where the bank account is held.
bankAccount .accountTypestringType of bank account. Only required for the Dominican Republic.
bankAccount .bankNamestringName of the bank. Only required for the Dominican Republic.
bankAccount .documentIdentifierstringUnique identifier of the document linked to the account.
premiumSpreadnumberAdditional percentage applied for premium services.

​
📘 Example Response

{
    "success": true,
    "data": {
        "id": "0483907e-ca31-432c-8234-fc401a921ef9",
        "userId": "d3127f5f-ff64-47f9-a9cc-ff603862eca6",
        "status": "PENDING",
        "cryptoAmount": 0.26,
        "fiatAmount": 4.728013,
        "exchangeRate": 18.184665,
        "tokenSymbol": "USDC",
        "blockchainSymbol": "POL",
        "fiatCurrency": "MXN",
        "createdAt": "2025-06-09T21:51:32.288Z",
        "completedAt": null,
        "destinationWalletAddress": "0x4cd63f6e9b8885dd502012f7b008b54d17a56e6f",
        "bankAccount": {
            "country": "MX",
            "accountIdentifier": "012345678902422382",
            "isVerified": true
        },
        "premiumSpread": 0.005
    }
}

​
⚠️ Important Notes & Requirements

  • Partner API Key is mandatory: All requests must include a valid PartnerApiKey in the header. Get your API key.
  • User must be verified: The user (userId) must have completed KYC and have an will go through an account verification process. The verification is only made once.
  • Supported Countries: Only flows from MX (Mexico) and DO (Dominican Republic) are currently supported.
  • Amount Limits: Crypto amounts must respect the minimum and maximum thresholds defined in the partner agreement.
  • Valid Blockchain & Token name: Ensure blockchainSymbol and tokenSymbol are retrieved from valid sources. Contact support for available options.
  • Wallets: Each wallet MUST be of the same type of the chain, you can’t use a EVM wallet in a SVM chain

​
✅ Use Cases

  • User Payout: Initiate a crypto-to-fiat payout to a verified user.
  • B2C Integration: Allow individual users to off-ramp from within your app or service.
  • B2B or Corporate Flows: Automate withdrawals to company bank accounts after receiving crypto payments.

Headers

​
partner-api-key
string
required

Api key for the affiliated partner that is performing the request

Body

application/json
​
userId
string
required

Identifier for the user

Example:

"8374f327-38bd-4b0b-b8a7-2524599eb903"

​
destinationWalletAddress
string
required

Wallet address of the user making the transaction.

Example:

"0x4d2f3d8f83b6f2f8e0f3f4f3f3f3f3f3f3f3f3f3"

​
fiatCurrency
enum<string>
required

Identifier for the fiat currency which the user will rec.

Available options:
MXN,
DOP,
USD,
EUR
Example:

"MXN"

​
blockchainSymbol
enum<string>
required

Identifier for the blockchain to token from which the conversion will be made.

Available options:
POL,
SOL,
BASE,
ARB,
BSC,
OP,
WLD,
STK,
ETH,
MTN,
CORE
Example:

"BASE"

​
tokenSymbol
enum<string>
required

Identifier for the token from which the conversion will be made.

Available options:
USDC,
USDT,
MXNe,
SOL,
ETH,
wBTC,
cbBTC,
PYSUD,
POL,
BNB,
WLD,
STK,
USDY,
CORE,
USDC.e,
wUSDL,
CoreBTC,
MATIC,
USDbC
Example:

"ETH"

​
quoteId
string

Identifier for the quote to be used for the transaction.

​
fiatAmount
number

Amount of fiat currency to be converted to crypto currency.

Example:

10200

​
cryptoAmount
number

Amount of cryptocurrency to be received in conversion.

Example:

10200

​
premiumSpread
number

Spread percentage to be applied to the exchange rate

Example:

0.01

Response

201 - application/json
​
success
boolean
Example:

true

​
data
object