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

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, selected network, and expiry. Quotes are short-lived and should be registered promptly.
POST /v1/quotes/best is not called by the SDK today. Use the raw API directly when you want Vortex to select the best available route, then pass the returned quote into the SDK ramp flow.

2. Register The Ramp#

Use POST /v1/ramp/register with the quote ID and 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. On BRL buy flows, the SDK calls POST /v1/ramp/update inside registerRamp to submit presigned transactions. 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-18 18:19:06
Previous
Authentication And Partner Keys
Next
Ephemeral Key Custody
Built with