# Generate Widget URL
Generate a signed widget URL to embed the ramp experience in an iframe. Server-side signing ensures wallet addresses are tamper-proof. Works for both buy (on-ramp) and sell (off-ramp) modes.
The on-ramp endpoint defaults to `buy` mode; the off-ramp endpoint defaults to `sell` mode.
## Request
### Headers
:::note Public Endpoint
This endpoint does not require authentication headers.
:::
### Body Parameters
## Response
### Success (200 OK)
```json
{
"success": true,
"data": {
"widgetUrl": "https://buy.onramper.com/?apiKey=...&mode=buy&defaultFiat=usd&defaultCrypto=BTC&wallets=btc:bc1q...&signature=abc123",
"embedMode": "iframe"
},
"message": "Widget URL generated"
}
```
### Response Fields
### Error Responses
## Embedding the Widget
```html
```
## Examples
```bash
# Buy widget
curl -X POST https://api.zenpayz.com/payment/api/v1/on-ramp/widget-url \
-H "Content-Type: application/json" \
-d '{
"mode": "buy",
"defaultFiat": "usd",
"defaultCrypto": "BTC",
"wallets": "btc:bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
"successRedirectUrl": "https://yourapp.com/success"
}'
# Sell widget
curl -X POST https://api.zenpayz.com/payment/api/v1/off-ramp/widget-url \
-H "Content-Type: application/json" \
-d '{
"defaultFiat": "usd",
"defaultCrypto": "BTC"
}'
```
```javascript
// Generate buy widget URL
const response = await fetch('https://api.zenpayz.com/payment/api/v1/on-ramp/widget-url', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
mode: 'buy',
defaultFiat: 'usd',
defaultCrypto: 'BTC',
wallets: 'btc:bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
successRedirectUrl: 'https://yourapp.com/success',
}),
});
const { data } = await response.json();
// Embed in iframe
const iframe = document.createElement('iframe');
iframe.src = data.widgetUrl;
iframe.style.cssText = 'border:none; border-radius:12px; width:482px; height:660px;';
iframe.allow = 'accelerometer; autoplay; camera; gyroscope; payment';
document.getElementById('widget-container').appendChild(iframe);
```
```python
import requests
# Generate buy widget URL
response = requests.post(
"https://api.zenpayz.com/payment/api/v1/on-ramp/widget-url",
json={
"mode": "buy",
"defaultFiat": "usd",
"defaultCrypto": "BTC",
"wallets": "btc:bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
"successRedirectUrl": "https://yourapp.com/success",
},
)
data = response.json()["data"]
print(f"Widget URL: {data['widgetUrl']}")
print(f"Embed mode: {data['embedMode']}")
```
## Integration Flow (Widget Mode)
```
1. POST /on-ramp/widget-url → Get signed widget URL
2. Embed widgetUrl in iframe → User completes purchase inside widget
3. User redirected to success/failure URL when done
```
## Next Steps
- [Config](/docs/rest-api/endpoints/ramp/config) -- Check integration mode (widget vs API)
- [Wallet Addresses](/docs/rest-api/endpoints/ramp/wallet-addresses) -- Understand wallet resolution
- [Buy Checkout](/docs/rest-api/endpoints/ramp/buy-checkout) -- API mode alternative