1. Documentation
Vortex
  • Documentation
    • Overview
    • Quick Start With The SDK
    • Authentication And API Keys
    • Ramp Lifecycle
    • Ephemeral Key Custody
    • Quotes And Pricing
    • Webhooks
    • Widget Integration
    • Fiat Corridors
    • Sandbox
    • Production Checklist
    • AI Agent Integration
    • KYB Deep Link
  • 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
    • Authentication
      • List the user's API keys
      • Create a user-linked API key pair
      • Revoke an API key
      • Request an email OTP
      • Verify an email OTP
    • 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
      • ListUserApiKeysResponse
      • Networks
      • OnChainToken
      • PaymentData
      • PaymentMethod
      • PresignedTx
      • QuoteResponse
      • RampCurrency
      • RampDirection
      • RampErrorLog
      • RampPhase
      • RampProcess
      • RegisterRampRequest
      • SimpleStatus
      • StartKYC2Request
      • StartKYC2Response
      • StartRampRequest
      • TaxIdType
      • TriggerOfframpRequest
      • TriggerOfframpResponse
      • UnsignedTx
      • UpdateRampRequest
      • UserApiKeyErrorResponse
      • UserApiKeyPairResponse
      • ValidatePixKeyResponse
  1. Documentation

Quick Start With The SDK

This page walks through complete BRL and bank-transfer-corridor (USD, MXN, COP, ARS) ramps 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 BRL KYC level 1 or higher, and the SDK must be authenticated with that user's own user-linked sk_* key: the user's CPF/CNPJ is derived from the authenticated account. The taxId field is deprecated — if you still send it, it must match the tax ID on the account or registration is rejected. Partner keys cannot drive KYC and cannot register ramps; 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.
The PIX payout goes to pixDestination, which must belong to the user. To pay out to a different recipient, pass receiverTaxId with the recipient's CPF/CNPJ; it defaults to the user's own tax ID.

Signing The User Transaction With Wagmi#

The user-owned transactions are EVM typed-data payloads or EVM transactions. Keep wallet prompts in your application and let the SDK handle classification and submission:
Validate every field before signing: chainId, verifyingContract, value, to, and data must match what your application requested. Never sign payloads blindly.

USD, MXN, COP And ARS Ramps#

USD, MXN, COP, and ARS settle through Vortex's local payment partners over the user's domestic banking rail. Pass the rail identifier as from (buy) or to (sell):
Fiat currencyRail identifierPayment rail
USD"ach"ACH bank transfer
MXN"spei"SPEI transfer
COP"ach"Colombian bank transfer
ARS"cbu"CBU bank transfer
All four corridors support buys and sells on EVM networks; AssetHub is not available for these corridors. The examples below use MXN — for the other currencies, substitute the fiat token and the rail identifier from the table. See Fiat Corridors for onboarding, fiat accounts, and limits.

Onramp (Buy)#

The user pays fiat off-chain; crypto is delivered to destinationAddress on the quoted network.
No user-signed on-chain transactions are required for onramp. The SDK signs ephemeral transactions during registerRamp.
Quotes can be requested without any key (anonymous rate discovery). Registering the ramp requires the user to be onboarded first: authenticate the SDK with that user's own user-linked secretKey (the sk_* key created by that user), and the same user must have completed KYC for the corridor's country. The key and the KYC record belong to the same account, so registration resolves to the user's verified payment profile automatically. A publicKey-only registration, or a partner-scoped sk_* with no user, is rejected.
Partner sk_* keys cannot drive this KYC, and the SDK cannot mint keys or run KYC — onboard the user through the Vortex app or Widget first, then use their sk_* key (shown only once, at creation; see Authentication And API Keys for minting it programmatically). This applies to buys and sells in all four corridors.

Offramp (Sell)#

Selling crypto for fiat in these corridors requires the user to sign one or more on-chain transactions with their own wallet. The SDK returns those transactions in unsignedTransactions.
fiatAccountId is opaque to the SDK. Create or look up the user's fiat account out-of-band and pass the ID here. It is required for offramp and optional for onramp.

Signing Offramp User Transactions#

Use the SDK helper to classify, sign, broadcast, and submit each entry in unsignedTransactions:
For wallets that call eth_signTypedData_v4 directly, set includeDomainType: true on submitUserTransactions or pass { includeDomainType: true } to getTypedDataToSign when using the lower-level helpers.

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-07-10 09:52:40
Previous
Overview
Next
Authentication And API Keys
Built with