/api/partner/v2/on-ramp

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

Header	Description
`partner-api-key`	API 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

`Parameter`	`Type`	Required	Description
`userId`	`string`	✅	ID of the user on whose behalf the transaction is created. The user’s identity must be verified first.
`fiatAmount`	`number`	🔘	Amount of fiat to be converted. Required if `cryptoAmount` is not provided.
`cryptoAmount`	`number`	🔘	Amount of crypto to be converted to fiat. Required if `fiatAmount` is not provided.
`fiatCurrency`	`string`	✅	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`).
`blockchainSymbol`	`string`	✅	Identifier of the blockchain used for the conversion. Refer to our supported blockchain list for availability.
`tokenSymbol`	`string`	✅	Identifier of the token used for the conversion. Refer to our supported token list for availability.
`premiumSpread`	`number`	🔘	Additional percentage applied to the exchange rate. This amount is fully awarded to the partner.
`destinationWalletAddress`	`string`	✅	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

Field	Type	Description
`id`	`string`	Unique ID of the created transaction.
`userId`	`string`	User ID associated with the transaction.
`status`	`string`	Current status of the transaction. Initially set to `"PENDING"`.
`cryptoAmount`	`number`	Amount of cryptocurrency being converted.
`fiatAmount`	`number`	Amount of fiat currency received after conversion.
`exchangeRate`	`number`	Exchange rate used for the crypto-to-fiat conversion.
`tokenSymbol`	`string`	Symbol of the cryptocurrency used.
`blockchainSymbol`	`string`	Symbol of the blockchain the cryptocurrency belongs to.
`fiatCurrency`	`string`	Currency code of the fiat currency received (e.g., `"MXN"`).
`createdAt`	`string`	ISO timestamp indicating when the transaction was created.
`completedAt`	`string`	ISO timestamp indicating when the transaction was completed, or `null` if pending.
`destinationWalletAddress`	`string`	Wallet where the user will receive the funds.
`bankAccount`	`object`	Information about the user’s bank account.
`bankAccount .isVerified`	`boolean`	Indicates whether the account has been verified and linked to the user.
`bankAccount .accountIdentifier`	`string`	Unique identifier of the account (CLABE for Mexico, Account Number for DO).
`bankAccount .country`	`string`	Country where the bank account is held.
`bankAccount .accountType`	`string`	Type of bank account. Only required for the Dominican Republic.
`bankAccount .bankName`	`string`	Name of the bank. Only required for the Dominican Republic.
`bankAccount .documentIdentifier`	`string`	Unique identifier of the document linked to the account.
`premiumSpread`	`number`	Additional 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

Show child attributes

data.id

string

required

Transaction identifier

Example:

"63f51f11-6869-47b0-a109-ddb50ef20efb"

data.userId

string

required

User identifier

Example:

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

data.status

string

required

Transaction status

Example:

"PENDING_PAYMENT"

data.cryptoAmount

number

required

Amount of crypto currency involved in the transaction

Example:

2500

data.fiatAmount

number

required

Amount of fiat currency involved in the transaction

Example:

50000

data.exchangeRate

number

required

Exchange rate used for the transaction

Example:

19.53964594161554

data.tokenSymbol

enum<string>

required

Token symbol

Available options:

USDC,

USDT,

MXNe,

SOL,

ETH,

wBTC,

cbBTC,

PYSUD,

POL,

BNB,

WLD,

STK,

USDY,

CORE,

USDC.e,

wUSDL,

CoreBTC,

MATIC,

USDbC

Example:

"USDC"

data.blockchainSymbol

enum<string>

required

Blockchain symbol

Available options:

POL,

SOL,

BASE,

ARB,

BSC,

OP,

WLD,

STK,

ETH,

MTN,

CORE

Example:

"POL"

data.fiatCurrency

enum<string>

required

Fiat currency symbol

Available options:

MXN,

DOP,

USD,

EUR

Example:

"MXN"

data.createdAt

string

required

Transaction creation date

Example:

"2025-05-14T10:00:00Z"

data.completedAt

string | null

required

Transaction completion date (null if not completed)

data.destinationWalletAddress

string

required

Destination wallet address for the transaction

Example:

"0x7796d4f304bd84171ee6730ad0f69c07a47e786d"

data.bankAccount

object

required

Bank account information

Show child attributes

data.bankAccount.country

string

required

The country of the bank account

Example:

"MX"

data.bankAccount.accountIdentifier

string

required

The account identifier for the bank account (CLABE in MX, account number elsewhere)

Example:

"014680260346007120"

data.bankAccount.isVerified

boolean

required

Whether the account is verified

Example:

true

data.bankAccount.bankName

string

The name of the bank

Example:

"Santander"

data.bankAccount.accountType

string

The type of the account

Example:

"SAVINGS"

data.bankAccount.documentIdentifier

string

The document identifier used for verification (e.g. national tax / ID number)

Example:

"123abc"

data.bankAccount.documentType

string

Type of the document bound to the account (country specific)

Example:

"RNC"

data.bankAccount.iban

string

International Bank Account Number (SEPA / EU accounts)

Example:

"DE89370400440532013000"

data.bankAccount.bic

string

Bank Identifier Code (SWIFT BIC) for SEPA / EU accounts

Example:

"DEUTDEFF"

data.bankAccount.routingNumber

string

ABA routing number (US only, 9 digits)

Example:

"021000021"

data.crossFiatAmount

number

data.premiumSpread

number

Premium spread applied to the transaction (0 if not provided)

Example:

0.01

Capa Partner API - V2

​🔐 Headers

​📥 Request Body

​📨 Example Request

​📤 Response Body

​📘 Example Response

​⚠️ Important Notes & Requirements

​✅ Use Cases

Headers

Body

Response

🔐 Headers

📥 Request Body

📨 Example Request

📤 Response Body

📘 Example Response

⚠️ Important Notes & Requirements

✅ Use Cases