API Reference¶
This page provides a comprehensive reference for the UniVoucher API.
UniVoucher API 1.0.0¶
UniVoucher is the world's first decentralized tangible crypto gift card protocol that allows users to create and redeem crypto gift cards across multiple blockchains.
This API is completely free and public to use - no API key required! With a single version, you can directly integrate with our endpoints without any registration or authentication process.
This is a read-only API and is designed to provide information about the UniVoucher ecosystem. You can use it to retrieve details about gift cards, query cards associated with specific addresses or blockchains, check current protocol fees, and more...
To perform actions such as creating or redeeming gift cards, you must interact directly with the UniVoucher smart contract. Please refer to our Integration Guide for guidance.
As a decentralized application, UniVoucher does not rely on centralized servers. Gift cards are generated locally on users' devices and stored securely on the blockchain. This API is designed to index the blockchain data and provide a way to query it. It is not a full-featured API and is not intended to be used for any other purpose than to query the blockchain data.
Full API specification: openapi.yaml
UniVoucher Support: Telegram Group
Servers¶
| Description | URL |
|---|---|
| Production API Server | https://api.univoucher.com/v1 |
General¶
GET /health¶
Health Check
Description
Checks if the API is running properly and database is connected
Response 200 OK
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Response 503 Service Unavailable
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
GET /¶
API Information
Description
Returns API documentation and available endpoints
Response 200 OK
{
"name": "UniVoucher API v1",
"version": "1.0.0",
"description": "string",
"endpoints": {
"/cards": "Card-related endpoints",
"/fees": "Fee-related endpoints",
"/chains": "Chain-related endpoints",
"/admin": "Admin endpoints"
}
}
Schema of the response body
{
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "UniVoucher API v1"
},
"version": {
"type": "string",
"example": "1.0.0"
},
"description": {
"type": "string"
},
"endpoints": {
"type": "object",
"properties": {
"/cards": {
"type": "string",
"example": "Card-related endpoints"
},
"/fees": {
"type": "string",
"example": "Fee-related endpoints"
},
"/chains": {
"type": "string",
"example": "Chain-related endpoints"
},
"/admin": {
"type": "string",
"example": "Admin endpoints"
}
}
}
}
}
Cards¶
GET /cards/all¶
Get All Cards
Description
Overview
This endpoint retrieves cards with flexible filtering options and provides comprehensive statistics.
Statistics Only Mode
Setting limit=0 returns only statistics without card data:
GET /cards/all?creator=0x123&chain=56&limit=0
{
"total": 250,
"active": 150,
"redeemed": 80,
"cancelled": 20
} This is useful for dashboards or when you only need counts.
The belongTo Parameter
The belongTo parameter enables retrieving all cards associated with an address (as either creator or redeemer) in a single query.
Usage Scenarios:
- Basic usage: /cards/all?belongTo=0x123
Returns all cards where creator=0x123 OR redeemedBy=0x123 - With creator:
/cards/all?belongTo=0x123&creator=0x456
Returns cards where creator=0x456 AND redeemedBy=0x123 - With redeemedBy:
/cards/all?belongTo=0x123&redeemedBy=0x456
Returns cards where creator=0x123 AND redeemedBy=0x456 - With both:
/cards/all?belongTo=0x123&creator=0x456&redeemedBy=0x789
Returns cards where creator=0x456 AND redeemedBy=0x789 (ignoring belongTo)
Note: When both belongTo and specific filters (creator/redeemedBy) are provided, the explicit filters take precedence over the corresponding parts of belongTo.
Common Use Cases
- Wallet integration: /cards/all?belongTo={userAddress} to show all cards a user has created or received
- Gift tracking: /cards/all?creator={userAddress}&status=active to show unredeemed gifts sent
- Portfolio view: /cards/all?redeemedBy={userAddress} to show received gifts
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
belongTo |
query | string | No | Filter to cards created by OR redeemed by this address. If creator or redeemedBy are also specified, they take precedence over the corresponding parts of belongTo. | |
chain |
query | integer | No | Filter by chain ID | |
creator |
query | string | No | Filter by creator address | |
limit |
query | integer | 20 | No | Results per page. Set to 0 for stats only. |
page |
query | integer | 1 | No | Page number for pagination |
partner |
query | string | No | Filter by partner address used during redemption | |
redeemedBy |
query | string | No | Filter by redeemer address | |
sortDirection |
query | string | desc | No | Sort direction for results based on creation date |
status |
query | string | No | Filter by card status | |
tokenAddress |
query | string | No | Filter by token address (use 0x0000000000000000000000000000000000000000 for native currency) |
Response 200 OK
{
"total": 250,
"active": 150,
"redeemed": 80,
"cancelled": 20,
"page": 1,
"limit": 20,
"totalPages": 13,
"cards": [
{
"cardId": 1026123,
"slotId": "0xabcdef1234567890abcdef1234567890abcdef12",
"chainId": 1,
"chainName": "Ethereum",
"active": true,
"status": "active",
"tokenAddress": "0x0000000000000000000000000000000000000000",
"tokenAmount": "1000000000000000000",
"creator": "0x1234567890abcdef1234567890abcdef12345678",
"message": "Happy Birthday!",
"encryptedPrivateKey": "string",
"feePaid": "10000000000000000",
"createdAt": "2025-05-01T12:00:00.000Z",
"createdOnBlock": 22516300,
"creationHash": "0xabcdef...",
"redeemedBy": "0x9876543210abcdef1234567890abcdef12345678",
"partner": "0x1111222233334444555566667777888899990000",
"redeemedAt": "2022-04-13T15:42:05.901Z",
"redeemedOnBlock": 0,
"redemptionHash": "string",
"cancelledBy": "string",
"cancelledAt": "2022-04-13T15:42:05.901Z",
"cancelledOnBlock": 0,
"cancellationHash": "string"
}
]
}
Schema of the response body
{
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "Total number of cards matching criteria",
"example": 250
},
"active": {
"type": "integer",
"description": "Number of active cards",
"example": 150
},
"redeemed": {
"type": "integer",
"description": "Number of redeemed cards",
"example": 80
},
"cancelled": {
"type": "integer",
"description": "Number of cancelled cards",
"example": 20
},
"page": {
"type": "integer",
"description": "Current page number",
"example": 1
},
"limit": {
"type": "integer",
"description": "Results per page",
"example": 20
},
"totalPages": {
"type": "integer",
"description": "Total number of pages",
"example": 13
},
"cards": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Card"
}
}
}
}
Response 500 Internal Server Error
Refer to the common response description: InternalServerError.
GET /cards/single¶
Get Single Card
Description
Get a single card by ID or slot ID
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
query | integer | No | Card ID to look up (mutually exclusive with slotId) | |
slotId |
query | string | No | Slot ID to look up (mutually exclusive with id) |
Response 200 OK
{
"cardId": 1026123,
"slotId": "0xabcdef1234567890abcdef1234567890abcdef12",
"chainId": 1,
"chainName": "Ethereum",
"active": true,
"status": "active",
"tokenAddress": "0x0000000000000000000000000000000000000000",
"tokenAmount": "1000000000000000000",
"creator": "0x1234567890abcdef1234567890abcdef12345678",
"message": "Happy Birthday!",
"encryptedPrivateKey": "string",
"feePaid": "10000000000000000",
"createdAt": "2025-05-01T12:00:00.000Z",
"createdOnBlock": 22516300,
"creationHash": "0xabcdef...",
"redeemedBy": "0x9876543210abcdef1234567890abcdef12345678",
"partner": "0x1111222233334444555566667777888899990000",
"redeemedAt": "2022-04-13T15:42:05.901Z",
"redeemedOnBlock": 0,
"redemptionHash": "string",
"cancelledBy": "string",
"cancelledAt": "2022-04-13T15:42:05.901Z",
"cancelledOnBlock": 0,
"cancellationHash": "string"
}
Schema of the response body
{
"type": "object",
"properties": {
"cardId": {
"type": "integer",
"description": "Unique identifier for the card",
"example": 1026123
},
"slotId": {
"type": "string",
"description": "Address/public key of the card",
"example": "0xabcdef1234567890abcdef1234567890abcdef12"
},
"chainId": {
"type": "integer",
"description": "Blockchain chain ID",
"example": 1
},
"chainName": {
"type": "string",
"description": "Name of the blockchain",
"example": "Ethereum"
},
"active": {
"type": "boolean",
"description": "Whether the card is active",
"example": true
},
"status": {
"type": "string",
"description": "Status of the card",
"enum": [
"active",
"redeemed",
"cancelled"
],
"example": "active"
},
"tokenAddress": {
"type": "string",
"description": "Address of the token (address(0) for native currency)",
"example": "0x0000000000000000000000000000000000000000"
},
"tokenAmount": {
"type": "string",
"description": "Amount of tokens stored (as string to handle large numbers)",
"example": "1000000000000000000"
},
"creator": {
"type": "string",
"description": "Address of the card creator",
"example": "0x1234567890abcdef1234567890abcdef12345678"
},
"message": {
"type": "string",
"description": "Optional message attached to the card",
"example": "Happy Birthday!"
},
"encryptedPrivateKey": {
"type": "string",
"description": "Encrypted private key (optional)"
},
"feePaid": {
"type": "string",
"description": "Fee paid when creating the card",
"example": "10000000000000000"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the card was created",
"example": "2025-05-01T12:00:00.000Z"
},
"createdOnBlock": {
"type": "integer",
"description": "Block number when the card was created",
"example": 22516300
},
"creationHash": {
"type": "string",
"description": "Transaction hash of the creation transaction",
"example": "0xabcdef..."
},
"redeemedBy": {
"type": "string",
"description": "Address that redeemed the card (null if not redeemed)",
"example": "0x9876543210abcdef1234567890abcdef12345678"
},
"partner": {
"type": "string",
"description": "Partner address used during redemption (0x0000000000000000000000000000000000000000 if no partner or null if not redeemed)",
"example": "0x1111222233334444555566667777888899990000"
},
"redeemedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the card was redeemed (null if not redeemed)"
},
"redeemedOnBlock": {
"type": "integer",
"description": "Block number when the card was redeemed (null if not redeemed)"
},
"redemptionHash": {
"type": "string",
"description": "Transaction hash of the redemption transaction (null if not redeemed)"
},
"cancelledBy": {
"type": "string",
"description": "Address that cancelled the card (null if not cancelled)"
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the card was cancelled (null if not cancelled)"
},
"cancelledOnBlock": {
"type": "integer",
"description": "Block number when the card was cancelled (null if not cancelled)"
},
"cancellationHash": {
"type": "string",
"description": "Transaction hash of the cancellation transaction (null if not cancelled)"
}
}
}
Response 400 Bad Request
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Response 404 Not Found
Response 500 Internal Server Error
Refer to the common response description: InternalServerError.
Fees¶
GET /fees/current¶
Get Current Fees
Description
Get current fee percentages for all chains or a specific chain
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
chainId |
query | integer | No | Chain ID to filter by |
Response 200 OK
Schema of the response body
{
"oneOf": [
{
"type": "object",
"description": "Fees for all chains",
"additionalProperties": {
"type": "number",
"format": "float"
},
"example": {
"1": 0.01,
"8453": 0.01,
"56": 0.01
}
},
{
"type": "object",
"description": "Fee for specific chain",
"properties": {
"feePercentage": {
"type": "number",
"format": "float",
"example": 0.01
}
}
}
]
}
Response 404 Not Found
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Response 500 Internal Server Error
Refer to the common response description: InternalServerError.
GET /fees/history/{chainId}¶
Get Fee History
Description
Get fee update history for a chain
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
chainId |
path | integer | No | Chain ID |
Response 200 OK
{
"chainId": 1,
"chainName": "Ethereum",
"currentFeePercentage": 0.01,
"currentFeeBasisPoints": 100,
"history": [
{
"oldFeePercentage": 0.005,
"newFeePercentage": 0.01,
"oldFeeBasisPoints": 50,
"newFeeBasisPoints": 100,
"timestamp": "2025-04-15T10:23:45.000Z",
"transactionHash": "0xabcdef..."
}
]
}
Schema of the response body
{
"type": "object",
"properties": {
"chainId": {
"type": "integer",
"example": 1
},
"chainName": {
"type": "string",
"example": "Ethereum"
},
"currentFeePercentage": {
"type": "number",
"format": "float",
"example": 0.01
},
"currentFeeBasisPoints": {
"type": "integer",
"example": 100
},
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"oldFeePercentage": {
"type": "number",
"format": "float",
"example": 0.005
},
"newFeePercentage": {
"type": "number",
"format": "float",
"example": 0.01
},
"oldFeeBasisPoints": {
"type": "integer",
"example": 50
},
"newFeeBasisPoints": {
"type": "integer",
"example": 100
},
"timestamp": {
"type": "string",
"format": "date-time",
"example": "2025-04-15T10:23:45.000Z"
},
"transactionHash": {
"type": "string",
"example": "0xabcdef..."
}
}
}
}
}
}
Response 404 Not Found
Response 500 Internal Server Error
Refer to the common response description: InternalServerError.
Chains¶
GET /chains¶
Get Chains
Description
Get all chains or details for a specific chain
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
chain |
query | integer | No | Chain ID to filter by |
Response 200 OK
Response 404 Not Found
Response 500 Internal Server Error
Refer to the common response description: InternalServerError.
Schemas¶
Card¶
| Name | Type |
|---|---|
active |
boolean |
cancellationHash |
string |
cancelledAt |
string(date-time) |
cancelledBy |
string |
cancelledOnBlock |
integer |
cardId |
integer |
chainId |
integer |
chainName |
string |
createdAt |
string(date-time) |
createdOnBlock |
integer |
creationHash |
string |
creator |
string |
encryptedPrivateKey |
string |
feePaid |
string |
message |
string |
partner |
string |
redeemedAt |
string(date-time) |
redeemedBy |
string |
redeemedOnBlock |
integer |
redemptionHash |
string |
slotId |
string |
status |
string |
tokenAddress |
string |
tokenAmount |
string |
Chain¶
| Name | Type |
|---|---|
assetPlatformId |
string |
chainLogo |
string |
chainPrefix |
string |
contractAddress |
string |
deploymentBlock |
integer |
explorerUrl |
string |
feePercentage |
number(float) |
id |
integer |
name |
string |
nativeCurrencyDecimals |
integer |
nativeCurrencyLogo |
string |
nativeCurrencyName |
string |
nativeCurrencySymbol |
string |
rpcUrl |
string |
rpcUrl2 |
string |
Common responses¶
This section describes common responses that are reused across operations.
InternalServerError¶
Internal server error
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Tags¶
| Name | Description |
|---|---|
| General | General API information and health endpoints |
| Cards | Card-related endpoints for gift card management |
| Fees | Fee-related endpoints for protocol fee management |
| Chains | Chain-related endpoints for blockchain information |