Vortex
    • Overview
    • Vortex SDK
    • Quick Start With The SDK
    • Ramp Lifecycle
    • Ephemeral Key Custody
    • Authentication And Partner Keys
    • Sandbox
    • BRL / KYC notes
    • Production Checklist
    • Quotes
      • Quotes And Pricing
      • Get existing quote
        GET
      • Create a new quote
        POST
      • Create a quote for the best network
        POST
    • Vortex Widget
      • Widget parameters
      • Widget Integration
      • Generating widget URL (for existing quote)
        POST
      • Generating widget URL (for existing quote)
        POST
    • Ramp
      • Get ramp status
        GET
      • Get ramp history for wallet address
        GET
      • Register new ramp process
        POST
      • Update ramp process
        POST
      • Start ramp process
        POST
      • Get ramp error logs
        GET
    • Account Management
      • Brazil
        • Brazilian KYC Process Overview
        • Get status of the last ramp event for a user
        • Start KYC level 2 process for a user
      • Europe
        • Coming soon...
      • Get user's remaining transaction limits
        GET
      • Get KYC document upload URLs
        POST
      • Get user information
        GET
      • Create user or retry KYC
        POST
      • Submit KYC level 1 data
        POST
      • Get selfie liveness URL
        GET
      • Get user's KYC status
        GET
      • Validate Pix key
        GET
    • Webhooks
      • Overview
      • Webhooks
      • Register Webhook
      • Delete Webhook
    • Public Key
      • Overview
      • Public Key
    • Reference Data
      • Supported Payment Methods
      • Supported Cryptocurrencies
      • Supported Countries
      • Supported Fiat Currencies
    • Schemas
      • Schemas
      • StartKYC2Response
      • GetKycStatusResponse
      • ValidatePixKeyResponse
      • GetUserRemainingLimitResponse
      • TriggerOfframpRequest
      • TriggerOfframpResponse
      • BrlaAddress
      • TaxIdType
      • CreateSubaccountRequest
      • CreateSubaccountResponse
      • KYCDocType
      • KYCDataUploadFileFiles
      • StartKYC2Request
      • GetUserResponse
      • StartRampRequest
      • RampDirection
      • GetWidgetUrlLocked
      • CountryCode
      • PaymentMethod
      • SimpleStatus
      • FiatToken
      • OnChainToken
      • GetWidgetUrlRefresh
      • CreateBestQuoteRequest
      • GetRampHistoryTransaction
      • GetRampHistoryResponse
      • BrlaErrorResponse
      • RegisterRampRequest
      • AccountMeta
      • Networks
      • PaymentData
      • RampProcess
      • RampPhase
      • DestinationType
      • UnsignedTx
      • CleanupPhase
      • CreateQuoteRequest
      • QuoteResponse
      • RampCurrency
      • UpdateRampRequest
      • PresignedTx
      • ErrorResponse
      • RampErrorLog
      • GetRampErrorLogsResponse
      • BrlaValidatePixKeyResponse
      • BrlaGetSelfieLivenessUrlResponse
      • AveniaDocumentType
      • AveniaKYCDataUploadRequest
      • DocumentUploadEntry
      • AveniaKYCDataUploadResponse
      • KycLevel1Payload
      • KycLevel1Response

    Ramp Lifecycle

    Every Vortex ramp follows the same high-level lifecycle.

    1. Create A Quote#

    Use POST /v1/quotes when the route and network are known. Use POST /v1/quotes/best when Vortex should evaluate eligible routes and return the best available quote for the requested amount and currency pair.
    A quote contains the input amount, expected output amount, source and destination, fee breakdown, payment method, network, and expiry. Quotes are short-lived and should be registered promptly.
    POST /v1/quotes/best is not called by the SDK today. To use it, call the raw API directly with the same body shape as POST /v1/quotes (plus optional countryCode) and pass the returned quote into sdk.registerRamp(...).

    2. Register The Ramp#

    Use POST /v1/ramp/register with the quote ID and the public addresses of the ephemeral accounts created for this ramp. The response returns a rampId, current ramp state, and any unsigned transactions that must be signed before processing can continue.
    Only public addresses are sent to Vortex. The matching ephemeral secret keys must stay with the SDK or API client.

    3. Update The Ramp#

    Use POST /v1/ramp/update to submit signed transactions and route-specific transaction hashes.
    The SDK performs this automatically for supported flows. Note that on BRL buy flows the SDK calls POST /v1/ramp/update inside registerRamp to submit the presigned transactions; there is no separate updateRamp step for buys. On sells, sdk.updateRamp(quote, rampId, { ... }) is used to submit additional route-specific transaction hashes after off-chain steps complete.
    Direct API integrations must ensure that each signature or transaction hash matches the transaction returned by Vortex for the same ramp and phase.

    4. Start The Ramp#

    Use POST /v1/ramp/start after required signatures, transaction hashes, and fiat payment steps are complete. For BRL buy flows, call start after the user completes the PIX payment.

    5. Track Status#

    Use GET /v1/ramp/{id} to retrieve current state, or configure webhooks to receive lifecycle events asynchronously. GET /v1/ramp/{id}/errors returns the error log for a ramp and is useful for support tooling.
    Production integrations should persist the quoteId, rampId, partner order ID, user/session identifier, and any local ephemeral-key backup reference needed for support or recovery.
    Modified at 2026-05-16 09:36:40
    Previous
    Quick Start With The SDK
    Next
    Ephemeral Key Custody
    Built with