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

Quick Start With The SDK

This page walks through a complete BRL ramp end-to-end using @vortexfi/sdk. The SDK is for trusted Node.js environments only.

Install#

Initialize#

publicKey is attached to quote requests for partner attribution and discount eligibility. secretKey is sent as the X-API-Key header on authenticated requests and must only be used server-side.
Constructing VortexSdk opens three WebSocket connections (Pendulum, Moonbeam, Hydration). Reuse one instance per process; do not construct a new SDK per request.

BRL Onramp (Buy)#

The user must have completed BRLA KYC level 1 or higher under the same taxId. Partner sk_* keys cannot drive BRLA KYC; onboard the user through the Vortex app or Widget first.

BRL Offramp (Sell)#

Selling crypto for BRL requires the user to sign one transaction with their own wallet. The SDK returns those transactions for you to route to the user's wallet provider.

Signing The User Transaction With Wagmi#

The user-owned transactions are EVM typed-data payloads. With wagmi:
Validate every field before signing: chainId, verifyingContract, value, to, and data must match what your application requested. Never sign payloads blindly.

Tracking Status#

Poll for user-facing screens, use webhooks for back-office reconciliation:
See Webhooks.

Updating A Ramp#

Most updates happen inside the SDK. For BRL buys, registerRamp already submits the presigned ephemeral transactions via POST /v1/ramp/update before returning. You typically only call submitUserSignature / submitUserTxHash explicitly for offramp user transactions, then startRamp.

Why The SDK Is Preferred#

The SDK creates fresh ephemeral accounts per ramp, signs the transactions Vortex returns, submits ramp updates, and can persist a local backup of ephemeral secrets. This removes the most error-prone parts of a custom integration.
If you disable SDK key storage with storeEphemeralKeys: false, your application must provide an equivalent secure backup. The default backup is an unencrypted JSON file named ephemerals_{rampId}.json written to the Node process's current working directory. Treat it as sensitive key material; encrypt it, restrict the directory, or disable storage and implement your own store. See Ephemeral Key Custody.
Modified at 2026-05-19 08:33:52
Previous
Overview
Next
Authentication And Partner Keys
Built with