Create widget session

Production

POST

/v1/session/create

Creates a hosted Vortex Widget session and returns the URL to open for the user.

This single endpoint supports two mutually exclusive request shapes:

Fixed quote (GetWidgetUrlLocked) — pass a quoteId you created via POST /v1/quotes. The widget uses that exact quote and does not refresh it. If the quote expires before the user finishes, they must close the window and start over.

Auto-refresh (GetWidgetUrlRefresh) — pass the route parameters (network, rampType, inputAmount, plus fiat / cryptoLocked / paymentMethod as relevant for the direction). The widget creates and refreshes quotes on demand for the user.

Use the example switcher below to see the request shape for each mode. externalSessionId is required in both modes and is echoed back in webhook payloads.

Request

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Returned when a fixed-quote session was created.

Bodyapplication/json

🟢201

🟠400

🟠404

Request Example

Shell

JavaScript

Java

Swift

cURL

Auto-refreshFixed quote

curl --location '/v1/session/create' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "pk_live_...",
    "callbackUrl": "https://partner.example.com/ramp/complete",
    "cryptoLocked": "USDC",
    "externalSessionId": "my-session-id",
    "fiat": "BRL",
    "inputAmount": "150",
    "network": "polygon",
    "paymentMethod": "pix",
    "rampType": "BUY",
    "walletAddressLocked": "0x1234567890123456789012345678901234567890"
}'

Response Example

200 - Success

{
    "url": "https://www.vortexfinance.co/widget?externalSessionId=my-session-id&quoteId=quote_01HXY..."
}

Modified at 2026-07-17 17:44:02

AI Agent Integration

Create a new quote