Vortex
    Vortex
    • General overview
    • Vortex Ramp Integration Guide
    • Vortex SDK
    • Sandbox Environment
    • Quotes
      • Get existing quote
        GET
      • Create a new quote
        POST
      • Create a quote for the best network
        POST
    • Vortex Widget
      • Widget parameters
      • Generate a widget URL (with quote refresh)
        POST
      • Generating widget URL (for existing quote)
        POST
    • Ramp
      • Get ramp status
        GET
      • Register new ramp process
        POST
      • Update ramp process
        POST
      • Start ramp process
        POST
    • Account Management
      • Brazil
        • Brazilian KYC Process Overview
        • Get user's remaining transaction limits
        • Get user information
        • Get status of the last ramp event for a user
        • Create user or retry KYC
        • Get user's KYC status
        • Start KYC level 2 process for a user
      • Europe
        • Coming soon...
    • Webhooks
      • Overview
      • Register Webhook
        POST
      • Delete Webhook
        DELETE
    • Public Key
      • Overview
      • Public Key
        GET
    • Supported Payment Methods
      GET
    • Supported Cryptocurrencies
      GET
    • Supported Countries
      GET
    • Supported Fiat Currencies
      GET

    Vortex SDK

    Vortex SDK (https://www.npmjs.com/package/@vortexfi/sdk) was implemented to avoid the need for ephemeral account creation, and handling signing process.
    Any Vortex ramp process always implements the register - update - ramp sequence. Since any ramp requires different information to be sent by the user during the update stage, the SDK implements an easy-to-use interface which is generic for any ramp, as well as the corresponding typing.

    Getting started#

    The following snippets demonstrate the general steps required for a generic ramp.
    1.
    Setup the SDK: First, you need to initialize the SDK. You can pass a config of type VortexSdkConfig to the constructor. The interface looks as follows:
    The parameters are mostly self-explanatory. Passing storeEphemeralKeys: true will store the secret keys of all the ephemeral accounts used for the ramp in a local file ${network}_ephemeral_key.json, with the name depending on the blockchain network being used. That JSON file stores an array of objects { address, rampId, secret } so that it's easy to find the ephemeral keys based on the ramp identifier.
    With this config, you can initialize an instance of the SDK.
    2.
    Create a Quote: First, get a price quote for the operation.
    3.
    Register the Ramp: Next, register the ramp using the quote and any extra data required for that specific ramp type (e.g. a destination wallet address or a PIX key). This call always returns the rampProcess and a list of unsignedTransactions.
    The unsignedTransactions array contains objects that your application must process. Each object has a standard structure:
    phase: A string identifying the purpose of the transaction (e.g., squidRouterApprove).
    txData: An object containing the raw transaction details.
    to: The destination EVM address (e.g., a contract address).
    data: The encoded calldata for the transaction.
    4.
    Update the Ramp: After you sign and broadcast the transactions from the previous step, you must call updateRamp. This step requires you to pass the resulting transaction hashes from the previous step.
    5.
    Start the Ramp: This is the final call to have Vortex begin executing the final leg of the process (e.g., sending the fiat or crypto).

    Signing Transactions#

    As mentioned in the previous section, certain ramp types necessitate that users sign and send transactions directly from their wallets. This SDK is designed to be flexible and does not depend on any specific signing package. Instead, it provides the raw data that needs to be sent, allowing users to manage the signing process independently.
    Below is an example of how you can utilize the wagmi package for signing transactions. This example demonstrates the process of acquiring the necessary data and handling the signing:

    BRL Onramp (Buy)#

    The following snippet shows how the SDK can be used to trigger a BRL onramp:

    BRL Offramps (Sell)#

    A BRL offramp requires an initial on-chain operation for the ramp to be triggered. Vortex uses the Squidrouter cross-chain swap service to start this process.
    After calling registerRamp, the returned unsignedTransactions array will contain data for a token approval and swap. You must sign and broadcast these transactions, then provide their resulting hashes to updateRamp to confirm the sale and trigger your ramp process.

    Current limitations#

    The Vortex SDK does not yet support the KYC/KYB required for onboarding new users. Only users who have already completed KYC/KYB verification can use the SDK to buy and sell tokens with Vortex.
    New users need to first initiate the KYC/KYB verification on app.vortexfinance.co.
    Once the process is finished, the sdk can be used for any further ramp requests, by only using the user's identifier for the corresponding country (eg.: tax-id for Brazil).
    Modified at 2025-10-23 15:36:02
    Previous
    Vortex Ramp Integration Guide
    Next
    Sandbox Environment
    Built with