The Vortex Widget is a hosted checkout that handles the user-facing ramp UX, signing, and ephemeral key custody for you. It is the recommended browser path when you do not need a fully custom UX or do not want to accept browser-side ephemeral custody.Endpoint#
This single endpoint creates a widget session and returns a hosted URL. It supports two mutually exclusive request shapes depending on whether you already have a quote.Authentication: send your credential's public value (pk_live_* / pk_test_*) as X-Public-Key for attribution. The body apiKey field remains accepted for widget compatibility; if both are present, they must match. Never expose the corresponding secret in widget or browser code.externalSessionId is required in both modes. It is your own opaque identifier for the session and is echoed back in webhook payloads so you can correlate events to your records.Mode A: Fixed Quote#
Use this when your application has already created a quote via POST /v1/quotes and wants the widget to lock in that exact price.{
"quoteId": "quote_01HXY...",
"externalSessionId": "my-session-id",
"callbackUrl": "https://partner.example.com/ramp/complete",
"walletAddressLocked": "0x1234567890123456789012345678901234567890"
}
Fields#
| Field | Required | Description |
|---|
quoteId | yes | ID of an existing quote (POST /v1/quotes). The widget locks in this quote and will not refresh it. |
externalSessionId | yes | Your opaque session identifier. Returned in webhook payloads. |
callbackUrl | no | URL the widget redirects to after the user successfully creates the transaction. |
walletAddressLocked | no | Lock the destination wallet address in the widget UI so the user cannot edit it. |
The quote does not refresh automatically. If it expires before the user completes checkout, the user must close the widget and your application must create a fresh quote and a fresh session.{ "url": "https://www.vortexfinance.co/widget?externalSessionId=my-session-id"eId=quote_01HXY..." }
Mode B: Auto-Refresh#
Use this when you want the widget to handle quoting for you. You pass the route definition; the widget creates and refreshes quotes on demand for the user.{
"externalSessionId": "my-session-id",
"rampType": "BUY",
"network": "polygon",
"inputAmount": "150",
"fiat": "BRL",
"cryptoLocked": "USDC",
"paymentMethod": "pix",
"callbackUrl": "https://partner.example.com/ramp/complete",
"walletAddressLocked": "0x1234567890123456789012345678901234567890"
}
Fields#
| Field | Required | Description |
|---|
externalSessionId | yes | Your opaque session identifier. Returned in webhook payloads. |
rampType | yes | "BUY" (fiat → crypto) or "SELL" (crypto → fiat). |
network | yes | EVM or Substrate network for the crypto leg (e.g. "polygon", "base", "assethub"). |
inputAmount | yes | Decimal string in the smallest commonly used unit of the input currency (e.g. "150" for 150 BRL). |
fiat | no | Fiat currency for the fiat leg (e.g. "BRL"). Required in practice for fiat-side ramps. |
cryptoLocked | no | Pre-selects and locks the crypto asset in the widget (e.g. "USDC"). |
paymentMethod | no | Payment rail (e.g. "pix"). Required in practice for buy flows. |
apiKey | no | Legacy body transport for the public credential value. Prefer X-Public-Key; if both are present, they must match. |
countryCode | no | ISO-3166 alpha-2 country code to pre-filter eligible options. |
partnerId | no | Partner identifier for attribution. |
callbackUrl | no | URL the widget redirects to after the user successfully creates the transaction. |
walletAddressLocked | no | Lock the destination wallet address in the widget UI so the user cannot edit it. |
Vortex validates the route on session creation by attempting to create a probe quote with the supplied parameters; invalid combinations return 400.{ "url": "https://www.vortexfinance.co/widget?externalSessionId=my-session-id&rampType=BUY&network=polygon&inputAmount=150&fiat=BRL&cryptoLocked=USDC&paymentMethod=pix" }
Which Mode Goes With Which Fields#
If you have a quoteId | Use Mode A (Fixed Quote). Do not include any auto-refresh route fields. |
|---|
If you do not have a quoteId | Use Mode B (Auto-Refresh). You must include the route definition fields. |
The request body shape is detected by the presence of quoteId. Mixing fields between the two modes is not supported.Open the returned URL in a popup, iframe, or top-level redirect.Receiving Results#
Subscribe to widget events through webhooks using the session identifier:{
"url": "https://partner.example.com/vortex/webhook",
"sessionId": "my-session-id",
"events": ["TRANSACTION_CREATED", "STATUS_CHANGE"]
}
sessionId so you can correlate events back to your externalSessionId.Webhook management uses the corresponding server-side secret through X-API-Key. If an integration configures both public and secret values, keep them from the same credential; mixed credentials return 403 CREDENTIAL_MISMATCH.| Scenario | Use |
|---|
| Browser / mobile app, hosted UX | Widget |
| Custom browser UX on a Vortex-approved origin, accepting prototype localStorage custody | @vortexfi/sdk with Bearer auth |
| Custom Node.js UX | @vortexfi/sdk with a secret credential |
| Trusted Python backend | vortex-sdk-python |
| Other backend stacks | Direct API (AI Agent Integration) |
Modified at 2026-09-08 09:48:09
