---
title: "Create Ramp Widget Session"
method: POST
path: "/v1/ramp-widget"
tags: ["Ramp Widget"]
---

# Create Ramp Widget Session

`POST /v1/ramp-widget`

Generate a session token and widget URL for the ZBD Ramp widget.

## Headers

- `Content-Type` string

## Request body

- object
  - `email` string — Email address of the user launching the Ramp
  - `webhook_url` string — URL to receive webhook notifications
  - `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

## Response `200`

Successful response

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `500` — Internal Server Error

## Changes

- **2025-06-19** `745914fb2a7f` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zbdpay/apis/zbd-payments-api/changes/v1/ramp-widget/post.md)

---

[API](https://skmtc.dev/zbdpay/apis/zbd-payments-api.md) · [All operations](https://skmtc.dev/zbdpay/apis/zbd-payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zbdpay/zbd-payments-api/revisions/0d5fdd96023d/schema)