/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.

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

⚠️This endpoint requires authentication using a valid partner-api-key.

📥 Request Body

📨 Example Request

📤 Response Body

📘 Example Response

⚠️ Important Notes & Requirements

✅ Use Cases

⚠️
This endpoint requires authentication using a valid `partner-api-key`.