POST
/
api
/
v1
/
ramp-widget
Create Widget Session
curl --request POST \
  --url https://api.zebedee.io/api/v1/ramp-widget \
  --header 'Content-Type: application/json' \
  --header 'apikey: <apikey>' \
  --data '{
  "email": "<string>",
  "webhook_url": "<string>",
  "access_token": "<string>",
  "quote_currency": "<string>",
  "base_currency": "<string>",
  "destination": "<string>",
  "reference_id": "<string>",
  "metadata": {}
}'
{
  "success": true,
  "data": {
    "session_token": "eyJraWQiOiJzLWE1OWNkMjc4...",
    "widget_url": "https://ramp.zbdpay.com/?session=eyJraWQiOiJzLWE1OWNkMjc4...",
    "session_id": "ses_9n3f7h2u4b",
    "expires_at": "2025-06-09T12:00:00Z"
  }
}

​
Description

This endpoint creates a session token and widget URL that can be used to embed the ZBD Onramp widget in your game or application.

​
Usage

The onramp widget allows your users to purchase Bitcoin or USDC using their preferred fiat currency. The session creation process involves:

First

Create a session with user details and configuration options

Second

Receive a widget URL and session token to embed in your application

​
Configuration

​
Header Parameters

​
apikey
string
required

ZBD Project API Key

​
Content-Type
string

Content Type

​
Body Parameters

​
email
string
required

Email address of the user launching the Ramp

​
webhook_url
string
required

URL to receive webhook notifications

​
access_token
string

Existing user session token (for returning users)

​
quote_currency
string

Currency to convert from (e.g., USD)

​
base_currency
string

Currency to convert to (e.g., BTC)

​
destination
string

Destination address for the funds (Lightning Address, onchain address, or USDC address)

​
reference_id
string

Your internal reference ID for this transaction

​
metadata
object

Additional metadata for the transaction

curl -X POST https://api.zebedee.io/api/v1/ramp-widget \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -d '{
    "email": "user@example.com",
    "webhook_url": "https://yourapp.com/webhooks/zbd"
  }'

{
  "success": true,
  "data": {
    "session_token": "eyJraWQiOiJzLWE1OWNkMjc4...",
    "widget_url": "https://ramp.zbdpay.com/?session=eyJraWQiOiJzLWE1OWNkMjc4...",
    "session_id": "ses_9n3f7h2u4b",
    "expires_at": "2025-06-09T12:00:00Z"
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Please provide a valid email address"
  }
}

Common error codes:

  • INVALID_EMAIL - Email format is invalid
  • INVALID_WEBHOOK_URL - Webhook URL is not accessible
  • UNAUTHORIZED - Invalid API key
  • RATE_LIMITED - Too many requests

​
Webhook Events

Webhooks are sent as POST requests to your specified webhook_url.

​
Event Structure

All webhook events follow this structure:

{
  "id": "evt_2n4f8gu3nf",
  "type": "onramp.purchase.completed",
  "created_at": "2025-06-09T10:30:00Z",
  "livemode": true,
  "data": {
    // Event-specific data
  }
}