Unlimit hosted ramps

Unlimit flows use hosted ramp experiences. Prefer capability channel execute. The /channel/unlimit/* endpoints are provider-specific alternatives for integrations already built directly around Unlimit fields.

Prerequisites#

  • API key with Unlimit channel enabled
  • Profile context (session or x-profile-id + x-team-id)
  • Supported fiat, payment method, crypto, chain, and country from config/discovery
  1. Discover Unlimit capabilities under /channels or /channels/discovery
  2. POST /channels/quote with the capability id
  3. POST /channels/execute with a session
  4. Read walletFlow and open the URL in providerPayload
  5. Poll GET /channels/unlimit/{txId}
  6. If status returns a refresh-url step, call it and open the replacement URL

See Channel payments for shared examples.

Capability execution returns walletFlow: "external" for the hosted experience. Store the returned txId; the provider order identifier is not a replacement for the Vudy transaction id.

Provider-specific /channel/unlimit/* path#

On-ramp config and quote#

curl -sS https://api-stg.vudy.app/channel/unlimit/onramp/config \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "x-profile-id: PROFILE_UUID" \
  -H "x-team-id: TEAM_UUID"

curl -sS "https://api-stg.vudy.app/channel/unlimit/onramp/quote?amount=100&fiat=USD&payment=card&crypto=USDC&chainId=1&country=US" \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "x-profile-id: PROFILE_UUID" \
  -H "x-team-id: TEAM_UUID"

Create on-ramp hosted session#

curl -sS https://api-stg.vudy.app/channel/unlimit/onramp \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "x-profile-id: PROFILE_UUID" \
  -H "x-team-id: TEAM_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "fiat": "USD",
    "payment": "card",
    "crypto": "USDC",
    "chainId": 1,
    "country": "US",
    "redirectUrl": "https://your.app/unlimit/return",
    "language": "en"
  }'
const { data } = await fetch(
	"https://api-stg.vudy.app/channel/unlimit/onramp",
	{
		method: "POST",
		headers: {
			"x-api-key": process.env.VUDY_API_KEY,
			"x-profile-id": profileId,
			"x-team-id": teamId,
			"Content-Type": "application/json",
		},
		body: JSON.stringify({
			amount: 100,
			fiat: "USD",
			payment: "card",
			crypto: "USDC",
			chainId: 1,
			country: "US",
			redirectUrl: "https://your.app/unlimit/return",
			// wallet optional — defaults may apply
		}),
	},
).then((r) => r.json());

// { url, orderCustomId } — open url in browser / WebView

Provider-specific off-ramp#

Mirror on-ramp under /channel/unlimit/offramp, /offramp/config, and /offramp/quote. Off-ramp create uses the same core fields (amount, fiat, payment, crypto, chainId, country, optional wallet / language) without redirectUrl.

Provider-specific orders#

# List
curl -sS "https://api-stg.vudy.app/channel/unlimit/orders?limit=20" \
  -H "x-api-key: vudy_sandbox_YOUR_KEY"

# Detail
curl -sS https://api-stg.vudy.app/channel/unlimit/orders/ORDER_ID \
  -H "x-api-key: vudy_sandbox_YOUR_KEY"

The provider-specific create response contains { url, orderCustomId }. Open url. Order detail is keyed by the identifier stored for the order; use the id returned by order listing when it differs from orderCustomId.

Refresh a capability transaction#

For pending or expired capability transactions, status may return a refresh-url action:

curl -sS -X POST https://api-stg.vudy.app/channel/unlimit/TX_ID/refresh-url \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"amount":100,"redirectUrl":"https://your.app/unlimit/return","language":"en"}'

The response uses the standard execute shape (walletFlow, providerPayload, …). Open the replacement URL from data.providerPayload.

Status transitions#

Capability parent tx: pending → completed | failed | expired.

Poll channel transaction status or provider-specific order detail until terminal.

Next steps#