List Ramp Intents

Retrieve a paginated list of ramp intents for your merchant account. Supports filtering by status, type, and text search across intent IDs and customer emails.

GEThttps://api.zenpays.com/payment/api/v1/ramp-intents

Bearer · API key

Request

Headers

Header	Description
Authorization REQUIRED	Bearer {api_key}
x-merchant-id REQUIRED	Your merchant ID
x-request-id REQUIRED	Unique request ID for tracing

Authenticated Endpoint

This endpoint requires API key authentication. Only intents belonging to the authenticated merchant are returned.

Query Parameters

Parameter	Type	Description
page OPTIONAL	number1	Page number
limit OPTIONAL	number20	Results per page (max 100)
status OPTIONAL	string—	Filter by status: created, active, completed, expired, cancelled
type OPTIONAL	string—	Filter by type: buy or sell
search OPTIONAL	string—	Search by intent ID or customer email (partial match)

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "a1b2c3d4-uuid",
        "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8",
        "type": "buy",
        "fiatCurrency": "USD",
        "cryptoCurrency": "eth_ethereum",
        "amount": 100,
        "status": "completed",
        "customerEmail": "[email protected]",
        "wallets": [
          { "network": "ethereum", "address": "0x742d35Cc..." }
        ],
        "expiresAt": "2026-03-15T10:00:00.000Z",
        "completedAt": "2026-03-15T09:45:00.000Z",
        "createdAt": "2026-03-15T09:00:00.000Z",
        "updatedAt": "2026-03-15T09:45:00.000Z"
      }
    ],
    "meta": {
      "total": 42,
      "page": 1,
      "limit": 20,
      "totalPages": 3
    }
  },
  "message": "Ramp intents retrieved"
}

Response Fields

Intent Object

Parameter	Type	Description
intentId OPTIONAL	string	Unique intent identifier
type OPTIONAL	string	buy or sell
fiatCurrency OPTIONAL	string	Fiat currency code
cryptoCurrency OPTIONAL	string| null	Crypto identifier
amount OPTIONAL	number| null	Amount
status OPTIONAL	string	Current status
customerEmail OPTIONAL	string| null	Customer email
wallets OPTIONAL	array	Wallet addresses
depositCharges OPTIONAL	object| null	Fee breakdown for deposit phase (sell intents)
payoutCharges OPTIONAL	object| null	Fee breakdown for payout phase (sell intents)
expiresAt OPTIONAL	string	Expiry timestamp
completedAt OPTIONAL	string| null	Completion timestamp
createdAt OPTIONAL	string	Creation timestamp
updatedAt OPTIONAL	string	Last update timestamp

Meta Object

Parameter	Type	Description
total OPTIONAL	number	Total matching intents
page OPTIONAL	number	Current page
limit OPTIONAL	number	Results per page
totalPages OPTIONAL	number	Total pages

Examples

cURL

# List all intents (page 1)
curl https://api.zenpays.com/payment/api/v1/ramp-intents \
  -H "Authorization: Bearer zp_test_your_api_key" \
  -H "x-merchant-id: merch_abc123" \
  -H "x-request-id: req_list_001"

# Filter by status and type
curl "https://api.zenpays.com/payment/api/v1/ramp-intents?status=completed&type=sell&page=1&limit=10" \
  -H "Authorization: Bearer zp_test_your_api_key" \
  -H "x-merchant-id: merch_abc123" \
  -H "x-request-id: req_list_002"

# Search by email
curl "https://api.zenpays.com/payment/api/v1/[email protected]" \
  -H "Authorization: Bearer zp_test_your_api_key" \
  -H "x-merchant-id: merch_abc123" \
  -H "x-request-id: req_list_003"

JavaScript

const params = new URLSearchParams({
  status: 'completed',
  type: 'sell',
  page: '1',
  limit: '10',
});

const response = await fetch(
  `https://api.zenpays.com/payment/api/v1/ramp-intents?${params}`,
  {
    headers: {
      'Authorization': 'Bearer zp_test_your_api_key',
      'x-merchant-id': 'merch_abc123',
      'x-request-id': `req_${Date.now()}`,
    },
  }
);

const { data } = await response.json();
const { data: intents, meta } = data;

console.log(`Page ${meta.page} of ${meta.totalPages} (${meta.total} total)`);
intents.forEach((intent) => {
  console.log(`${intent.intentId} | ${intent.type} | ${intent.status}`);
});

Python

import requests

response = requests.get(
    "https://api.zenpays.com/payment/api/v1/ramp-intents",
    headers={
        "Authorization": "Bearer zp_test_your_api_key",
        "x-merchant-id": "merch_abc123",
        "x-request-id": "req_list_001",
    },
    params={
        "status": "completed",
        "type": "sell",
        "page": 1,
        "limit": 10,
    },
)

result = response.json()["data"]
intents = result["data"]
meta = result["meta"]

print(f"Page {meta['page']} of {meta['totalPages']} ({meta['total']} total)")
for intent in intents:
    print(f"{intent['intentId']} | {intent['type']} | {intent['status']}")

Next Steps

• Get Ramp Intent — Retrieve full details for a specific intent
• Create Ramp Intent — Create a new ramp intent
• Update Ramp Intent Status — Manually update intent status