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 '
{
  "userId": "8374f327-38bd-4b0b-b8a7-2524599eb903",
  "destinationWalletAddress": "0x4d2f3d8f83b6f2f8e0f3f4f3f3f3f3f3f3f3f3f3",
  "fiatCurrency": "MXN",
  "blockchainSymbol": "BASE",
  "tokenSymbol": "ETH",
  "quoteId": "<string>",
  "fiatAmount": 123,
  "cryptoAmount": 123,
  "premiumSpread": 123
}
'
{
  "success": true,
  "data": {
    "id": "63f51f11-6869-47b0-a109-ddb50ef20efb",
    "userId": "8374f327-38bd-4b0b-b8a7-2524599eb903",
    "status": "PENDING_PAYMENT",
    "cryptoAmount": 2500,
    "fiatAmount": 50000,
    "exchangeRate": 19.53964594161554,
    "tokenSymbol": "USDC",
    "blockchainSymbol": "POL",
    "fiatCurrency": "MXN",
    "createdAt": "2025-05-14T10:00:00Z",
    "completedAt": "<string>",
    "destinationWalletAddress": "0x7796d4f304bd84171ee6730ad0f69c07a47e786d",
    "bankAccount": {
      "country": "MX",
      "accountIdentifier": "014680260346007120",
      "isVerified": true,
      "bankName": "Santander",
      "accountType": "SAVINGS",
      "documentIdentifier": "123abc",
      "documentType": "RNC",
      "iban": "DE89370400440532013000",
      "bic": "DEUTDEFF",
      "routingNumber": "021000021"
    },
    "crossFiatAmount": 123,
    "premiumSpread": 0.01
  }
}
Creates an on-ramp transaction on behalf of a verified user. This converts fiat to crypto — the user deposits fiat via bank transfer and receives crypto at the specified wallet address.
For staging transaction testing, use the Mock Testing Guide.

​
Field Relationships

  • Provide quoteId OR (fiatCurrency + blockchainSymbol + tokenSymbol). When a quote is used, currency/token fields are inherited from the quote.
  • Provide either fiatAmount or cryptoAmount, not both.
  • Provide either destinationWalletAddress (inline) or walletAddressId (reference to a saved wallet).

​
Integration Flow

1

Create a user

POST /api/partner/v2/users
2

Complete KYC verification

POST /api/partner/v2/users//kyc/verification-link
3

Get a quote (optional)

POST /api/partner/v2/quotes — locks the exchange rate
4

Create on-ramp transaction

POST /api/partner/v2/on-ramp (this endpoint) — returns bank account details for the fiat deposit
5

User deposits fiat

The user sends fiat to the bank account returned in the bankAccount response field.

​
Important Notes

  • User must be KYC-verified before creating transactions.
  • Wallet type must match blockchain: An EVM wallet cannot be used on a Solana chain, and vice versa.
  • Amount limits: Fiat and crypto amounts must fall within the min/max thresholds defined in your partner agreement.

​
Use Cases

  • Buy Crypto: Enable users to purchase cryptocurrency using fiat deposited via bank transfer.
  • B2C Integration: Let individual users on-ramp from within your app.
  • Automated Purchases: Programmatically initiate fiat-to-crypto conversions for your users.

​
Error Codes

​
Common Errors

HTTP StatusCodeMessage
401UNAUTHORIZED”API Key is missing”
401UNAUTHORIZED”Invalid API Key format”
401UNAUTHORIZED”Invalid API Key”
403INVALID_PARTNER_FLOW”The partner has an invalid flow.”

​
Verified User Errors

HTTP StatusCodeMessage
400REQUIRED_USER_ID_ERROR”This endpoint requires a user id to be provided”
403USER_NOT_VERIFIED_ERROR”User is not allowed to perform the operations because has not completed the KYC verification.”

​
Endpoint-Specific Errors

HTTP StatusCodeMessage
400INVALID_USER_INPUT_ERROR”Invalid User Input”
400BAD_REQUEST”address must be a valid address”
400BAD_REQUEST”Either quoteId or fiatCurrency, blockchainSymbol, tokenSymbol, and at least one of fiatAmount or cryptoAmount must be provided”
400BAD_REQUEST”Fiat currency is disabled or does not exist”
400BAD_REQUEST”This blockchain and token combination is disabled or does not exist”
400QUOTE_EXPIRED”Quote has expired”
400BAD_REQUEST”Quote is not valid for ON_RAMP”
400INVALID_TOKEN_OPERATION_ERROR”Token cannot be operated as OTC, only stable coins are allowed”
400BAD_REQUEST”Either walletAddressId or destinationWalletAddress must be provided”
400BAD_REQUEST”Cannot create transaction: No supported banks configured for user with id: “
400INVALID_FIAT_AMOUNT_ERROR”Fiat amount is outside of the allowed range for ON_RAMP. Should be between and “
400INVALID_TOKEN_AMOUNT_ERROR”Token amount is outside of the allowed range for ON_RAMP. Should be between and “
403RECEIVER_CANNOT_INITIATE_TRANSACTION”Receiver accounts cannot initiate transactions directly.”

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.

​
cryptoAmount
number

Amount of cryptocurrency to be received in conversion.

​
premiumSpread
number

Spread percentage to be applied to the exchange rate

Response

201 - application/json
​
success
boolean
Example:

true

​
data
object