Docs
API
Bring the voucher catalogue and checkout into your site, app or shop.
Spec for your AI assistant
The whole API reference as one Markdown document: paste it into Claude Code, Cursor or any coding assistant to guide the integration.
Basics
- Base URL
- https://xyzvouchers.com/api
- Authentication
- An API key in every /v1 request:
Authorization: Bearer xyz_…. Keys are for creators: get yours below. Creator endpoints (/me) use the wallet session (Sign-In with Ethereum). - Limits per key
- 300 reads per minute and 30 writes per minute.
- Format
- JSON. Amounts are USDC units with 6 decimals, as strings (
"35000000"= 35 USDC). Ids are strings too.
Your API key
One key per wallet. It is created with a signature from your wallet: no transaction, no gas.
Sale and visibility
onSale- Sale status in the contract, switched by the creator at any time. A purchase needs both the voucher and its collection on sale.
isPublic- Whether the collection is listed in the catalogue. A private collection is left out of lists and search, but can still be fetched and bought by its id or link.
purchasable- Whether it can be bought right now. When it is <code>false</code>, show it as usual but tell the buyer that the issuer has temporarily disabled purchases: buying answers 409 <code>NOT_ON_SALE</code>.
Terms
Every /v1 response carries an X-Terms-Version header and a Link header to the Terms. Sending the purchase transaction means accepting them: show the buyer the notice in the terms object and the link before they sign.
Catalogue
By default it returns everything, on sale or not: purchasable tells whether it can be bought now. Private collections never appear in lists.
GET/v1/collectionsAPI key
Lists the public collections.
| Name | In | Type | Description |
|---|---|---|---|
| q | query | string ≤ 100 | Searches name and description. |
| creator | query | address | Only the collections of this address. |
| sort | query | newest | price_asc | price_desc | Order. By price uses the cheapest voucher on sale. |
| onSale | query | true | false | all | all (default): every one. true: the ones that can be bought. false: the ones that cannot. |
| limit | query | 1–100 (20) | Results per page. |
| offset | query | 0–100000 (0) | Results to skip. |
{
"items": [{
"id": "12", "creator": "0x…", "name": "Spa Days", "description": "…", "imageCid": "bafkrei…",
"termsVersion": 1, "onSale": true, "isPublic": true, "purchasable": true,
"minPrice": "35000000", "voucherTypeCount": 2, "createdAt": 1763463600, "txHash": "0x…"
}]
}GET/v1/collections/{id}API key
A collection with its vouchers, also when it is private.
| Name | In | Type | Description |
|---|---|---|---|
| id | path | uint256 | Collection id. |
| onSale | query | true | false | all | Filters its vouchers: all (default), true or false. |
GET/v1/voucher-types/{id}API key
A voucher with its collection, on sale or not. purchasable tells whether it can be bought.
| Name | In | Type | Description |
|---|---|---|---|
| id | path | uint256 | Voucher id. |
{
"id": "31", "collectionId": "12", "name": "Relax", "price": "35000000", "onSale": true,
"attributes": [{ "traitType": "Duration", "value": "60 min" }], "sold": 4,
"purchasable": true,
"collection": { "id": "12", "name": "Spa Days", "creator": "0x…", "onSale": true, "isPublic": true }
}Purchase
Two ways: a checkout link hosted on xyzvouchers, or the calldata for the buyer to sign in your own interface. Payment goes in USDC straight to the creator.
POST/v1/checkout-linksAPI key
Returns a permanent checkout link, the quote and the Terms notice.
| Name | In | Type | Description |
|---|---|---|---|
| typeId | body | string (uint256) | Voucher id. |
| quantity | body | 1–50 | Units. Each one is an NFT. |
| recipient | body | address | Who receives the NFTs. |
| ref | body | [a-z0-9-]{1,64} | Your attribution code (optional when buying). |
{
"url": "https://xyzvouchers.com/buy/31?qty=2&to=0x1111111111111111111111111111111111111111&ref=partner-acme",
"quote": {
"voucherType": { "id": "31", "collectionId": "12", "name": "Relax", "imageCid": "bafkrei…" },
"quantity": 2, "recipient": "0x1111111111111111111111111111111111111111", "payer": null,
"unitPrice": "35000000", "total": "70000000",
"refCode": "partner-acme", "ref": "0x22179a0de701fe4d00a7f05bbbbd511ea516f4dab2ed71617ce6834e7e409281",
"contract": "0x…", "usdc": "0x…", "chainId": 137
},
"terms": { "version": 1, "hash": "0x…", "url": "https://xyzvouchers.com/terms", "notice": "By sending this transaction the buyer accepts…" }
}POST/v1/purchase-calldataAPI key
Returns the exact approve and the purchase transactions, ready to sign.
| Name | In | Type | Description |
|---|---|---|---|
| typeId | body | string (uint256) | Voucher id. |
| quantity | body | 1–50 | Units. Each one is an NFT. |
| recipient | body | address | Who receives the NFTs. |
| payer | body | address | Who pays and signs the transaction. |
| ref | body | [a-z0-9-]{1,64} | Your attribution code (optional when buying). |
GET/v1/purchasesAPI key
Purchases made with your ref, newest first.
| Name | In | Type | Description |
|---|---|---|---|
| ref | query | [a-z0-9-]{1,64} | Your attribution code (optional when buying). |
| limit | query | 1–100 (20) | Results per page. |
| offset | query | 0–100000 (0) | Results to skip. |
GET/v1/termsAPI key
Current Terms version, its hash, its URL and the notice you must show.
Creators
For the creator's own tools. Sign in with their wallet and send the xyz_session cookie with each request.
GET/auth/nonce
Returns a single-use nonce for the sign-in message.
POST/auth/verify
Verifies the signed message and opens the session (xyz_session cookie).
| Name | In | Type | Description |
|---|---|---|---|
| message | body | SIWE (EIP-4361) | EIP-4361 message with the nonce. |
| signature | body | hex | Signature of the message with the wallet. |
GET/me/api-keysession
Whether the wallet can have a key (it created at least one voucher type) and its active key: prefix, creation and last use. Never the key itself.
POST/me/api-keysession
Creates the key, or renews it and revokes the previous one. Sign a SIWE message with a fresh nonce and the API key statement. Returns key only this once.
| Name | In | Type | Description |
|---|---|---|---|
| message | body | SIWE (EIP-4361) | SIWE message with the statement Create my xyzvouchers.com API key…, signed by the session wallet. |
| signature | body | hex | Signature of the message with the wallet. |
{ "key": "xyz_…", "prefix": "xyz_4f9a", "createdAt": "2026-11-19T10:00:00.000Z", "lastUsedAt": null }GET/me/creator-statssession
The creator's collections with their sale status and visibility, their vouchers, sales and issued NFTs.
| Name | In | Type | Description |
|---|---|---|---|
| visibility | query | public | private | all (all) | Filters by the collection's visibility. |
| onSale | query | true | false | all (all) | Filters by the collection's sale status. |
PATCH/me/collections/{id}session
Makes a collection public or private. Its creator only.
| Name | In | Type | Description |
|---|---|---|---|
| id | path | uint256 | Collection id. |
| isPublic | body | boolean | true: public. false: private. |
{ "collectionId": "12", "isPublic": false }Errors
Errors return the HTTP status and an error object with a stable code and a message.
{ "error": { "code": "NOT_ON_SALE", "message": "This voucher type or its collection is not on sale" } }| 400 | VALIDATION_ERROR | Parameters in the wrong format. |
| 401 | INVALID_API_KEY | Missing, unknown or revoked API key. |
| 401 | UNAUTHENTICATED | The wallet session is missing. |
| 403 | SANCTIONED | One of the addresses cannot use the service. |
| 403 | NOT_A_CREATOR | Only wallets that created a voucher type can have an API key. |
| 403 | SIGNER_MISMATCH | The message was signed by another wallet than the session’s. |
| 403 | NOT_COLLECTION_CREATOR | Only the creator of the collection can do this. |
| 404 | NOT_FOUND | It does not exist or has been removed. |
| 409 | NOT_ON_SALE | The voucher or its collection is not on sale. |
| 429 | RATE_LIMITED | Too many requests. Wait and retry. |
| 451 | UNAVAILABLE_FOR_LEGAL_REASONS | Not available in your region. |
| 503 | TERMS_UNAVAILABLE | Service temporarily unavailable. |