Vortex Ramp Integration Guide
This guide details the integration process for Vortex's on-ramp and off-ramp services. Integration typically involves three primary steps:1.
Obtaining a Quote: Define the terms of the desired transaction.
2.
Registering the Ramp: Prepare the transaction with necessary client-side and backend information.
3.
Starting the Ramp: Execute the transaction using pre-signed instructions.
1. Obtaining a Quote#
The first step for any ramp operation (on-ramp or off-ramp) is to obtain a quote. A quote specifies the exchange terms for a desired transaction and is valid for 10 minutes.To create a quote, call the Create a new quote endpoint with the details of the desired transaction.Example Request: Off-ramp 33 USDC from Polygon to BRL via PIXThe quoted output amount is guaranteed if the ramp is registered and started using this quote within its 10-minute validity period. A successful quote request will return a quoteId.2. Registering a ramp#
Once you have a valid quoteId, the next step is to register the ramp. This involves calling the Register new ramp process endpoint.A critical component for registering and executing a ramp is the use of ephemeral accounts. These are special-purpose accounts created on the client-side whose public keys are provided during registration to the Vortex backend. These accounts will be used to pre-sign transactions required for the ramp process.The Vortex SDK package will handle entirely the creation, management, and signing operations of these ephemeral accounts.Registering a ramp process for Brazil (PIX):#
For ramps involving Brazilian Reais (BRL) via PIX (both on-ramps and off-ramps), you must create ephemeral accounts on both Moonbeam and Pendulum. The public addresses of these accounts must be provided in the signingAccounts array.After successful registration, the API will return a rampId, which you will use in the "Start Ramp" step.On-Ramp#
For on-ramps (e.g., BRL to USDC), you need to provide:taxId: The user's Brazilian tax ID (CPF for individuals, CNPJ for companies).
destinationAddress: The blockchain address where the user will receive the cryptocurrency, on the chain specified in the initial quote.
(Assumes quoteId "8e4bca04-aa22-4f86-9ce5-80aaef58ef83" was obtained from the quoting step)Upon successful registration of an on-ramp, the API response will include a brCode string within the ramp object. This brCode is to be used by the end-user to make the PIX payment.Off-Ramp#
For off-ramps (e.g., USDC to BRL), you need to provide:taxId: The Vortex-registered user's Brazilian tax ID (CPF or CNPJ) who is initiating the off-ramp.
receiverTaxId: The tax ID (CPF or CNPJ) of the recipient of the BRL funds. This must match the owner of the bank account associated with the pixDestination.
pixDestination: The PIX key (e.g., CPF, CNPJ, email, phone, or random key) where the BRL funds will be deposited.
(Assumes quoteId "8e4bca04-aa22-4f86-9ce5-80aaef58ef83" was obtained from the quoting step)Registering a ramp for Euro (SEPA).#
3. Sending additional data.#
Before starting a ramp, the ephemeral transactions need to be signed, and depending on the ramp type, some extra additional information may be required post-register.For sending this information, the /update endpoint must be used. It can be called multiple times, and new data will be appeneded.3.1 Presigned transactions#
Upon successful validation from the previous register step, Vortex returns a set of unsignedTxs (unsigned transactions) within the API response to the registration call.These unsignedTxs are an array of transaction objects, primarily for Pendulum and Moonbeam networks.Example unsignedTxs structure (part of the registration response):"unsignedTxs": [
{
txData: '0x....',
phase: 'swap',
network: Pendulum,
nonce: 1,
signer: "6ftBY........HFb9rcPv",
meta?: any,
}
],
Additional data for an Off-Ramp (PIX)#
For off-ramps, there's an additional client-side step before calling the "Start Ramp" endpoint:1.
User Fund Transfer: The user needs to send their cryptocurrency (e.g., USDC) from their wallet to a specified address.
The details for this initial transfer transaction (e.g., destination address, amount) will be provided by Vortex, as part of the unsignedTxs transactions array.
2.
Transaction Hash(es): After the user sends their funds, one or more transaction hashes will be generated. These hashes must be provided in the additionalData field when calling the "Start Ramp" endpoint.
3.
Sign Vortex Transactions: Sign the unsignedTxs (received from the "Register Ramp" step) using the ephemeral accounts to generate the presignedTxs array.
4.
Start Ramp Call: Call the "Start Ramp" endpoint with the rampId, the presignedTxs, and the transaction hash(es) from the user's fund transfer.
(Assumes rampId "proc_12345" was obtained from registration, and user transaction hashes were obtained){
"rampId": "proc_12345",
"presignedTxs": [
{
"phase": "RampPhase",
"nonce": 1,
"signer": "GB2TP24WCY6BPGFX4SOGDHT7IGJRR7HCDQT2VL2MVCZJTJCGKMVGQGQB",
"meta": {},
"txData": "AAAAAKu..."
}
],
"additionalData": {
"squidRouterApproveHash": "0x123...",
"squidRouterSwapHash": "0x456..."
}
}
Starting onramps#
For the case of an onramp, a brCode string is returned after the Register new ramp process step is validated, along with the ramp process information. This code contains the required reference for the payment and quote amoun, and is ready to be used to make the PIX payment.The process is started by calling the Start ramp process endpoint without any aditional data besides the pre-signed transactions, and ONLY should be started once the user has made the payment over the pix system.Starting a ramp without payment completion puts the process in risk of delay if the payment is done later.Additional data with Vortex SDK#
Vortex SDK takes care of signing and sending the pre-signatures in the background, and only the user's additional data is required. The SDK's typing will help ensure all fields are specified correctly. Modified at 2025-08-12 12:54:27
