> For the complete documentation index, see [llms.txt](https://docs.universal.xyz/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.universal.xyz/docs/developers/integrate-the-issuance-and-redemption-universal-api/orders-api.md). # Orders API ### Overview The Orders API allows you to track the status of mint and burn operations. Each operation creates an order that can be queried to monitor progress and completion. ### Endpoints #### Get Orders Retrieves a paginated list of orders for the authenticated wallet. **Endpoint**: `GET /orders` **Headers**: ``` Authorization: Bearer ``` **Query Parameters**: * `limit` (integer, optional): Number of orders to return (default: 20, max: 100) * `offset` (integer, optional): Number of orders to skip for pagination (default: 0) * `type` (string, optional): Filter by order type (`mint` or `burn`) * `status` (string, optional): Filter by order status (see statuses below) **Response** (200 OK): ```json { "success": true, "data": { "orders": [ { "id": "12345", "type": "mint", "status": "completed", "sourceChain": "sol", "destinationChain": "base", "token": "SOL", "amount": "1500000000", "sourceWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "destinationWallet": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b1", "workflowId": "mint-workflow-abc123", "transactionHash": "0xabcdef1234567890...", "errorMessage": null, "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:32:45.000Z" }, { "id": "12344", "type": "burn", "status": "processing", "sourceChain": "base", "destinationChain": "xrp", "token": "uXRP", "amount": "5000000000000000000", "sourceWallet": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b1", "destinationWallet": "rN7n7otQDd6FczFgLdlqtyMVUXWqzp1GE1", "workflowId": "burn-workflow-xyz789", "transactionHash": null, "errorMessage": null, "createdAt": "2025-01-15T10:25:00.000Z", "updatedAt": "2025-01-15T10:26:30.000Z" } ], "pagination": { "limit": 20, "offset": 0, "total": 47, "hasMore": true } } } ``` **cURL Example**: ```bash curl -X GET "https://api.universal.xyz/issuance-redemption/orders?limit=10&type=mint&status=completed" \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." ``` ### Order Fields #### Basic Information * `id` (string): Unique order identifier * `type` (string): Order type - `mint` or `burn` * `status` (string): Current order status (see statuses below) * `createdAt` (string): ISO 8601 timestamp of order creation * `updatedAt` (string | null): ISO 8601 timestamp of last update #### Chain and Token Details * `sourceChain` (string): Chain where tokens are sent from * For mint: `sol`, `xrp`, `sui`, `doge`, `zec` * For burn: `base`, `arbitrum`, `katana`, `world`, `unichain` * `destinationChain` (string): Chain where tokens are received * For mint: `base`, `arbitrum`, `katana`, `world`, `unichain` * For burn: `sol`, `xrp`, `sui`, `doge`, `zec` * `token` (string): Token being transferred * For mint: `SOL`, `XRP`, `SUI`, `DOGE`, `ZEC` * For burn: `uSOL`, `uXRP`, `uSUI`, `uDOGE`, `uZEC` #### Amount and Addresses * `amount` (string): Amount in smallest unit (lamports, satoshis, wei, etc.) * `sourceWallet` (string): Source wallet address * `destinationWallet` (string): Destination wallet address #### Processing Details * `workflowId` (string): Temporal workflow ID for tracking internal processing * `transactionHash` (string | null): Blockchain transaction hash (null if not yet processed) * `errorMessage` (string | null): Error description if order failed (null otherwise) ### Order Statuses | Status | Description | Next Step | | --------------------- | ------------------------------------------------ | ----------------------------- | | `pending` | Order created, awaiting blockchain confirmation | Wait for confirmation | | `processing` | Blockchain deposit confirmed, workflow executing | Monitor for completion | | `minting` / `burning` | Actively minting or burning tokens | Near completion | | `completed` | Operation successfully completed | Check transactionHash | | `failed` | Operation failed | Review errorMessage | | `cancelled` | Operation cancelled (manual intervention) | Contact support if unexpected | ### Order Lifecycle #### Mint Order Lifecycle ```mermaid graph LR A[pending] --> B[processing] B --> C[minting] C --> D[completed] B --> E[failed] C --> E ``` 1. **pending**: Deposit detected on source chain, awaiting confirmations 2. **processing**: Confirmations received, workflow initiated 3. **minting**: Minting universal tokens on destination EVM chain 4. **completed**: Universal tokens minted and transferred to destination wallet 5. **failed**: Error occurred during processing (see errorMessage) #### Burn Order Lifecycle ```mermaid graph LR A[pending] --> B[processing] B --> C[burning] C --> D[completed] B --> E[failed] C --> E ``` 1. **pending**: Universal token transfer detected on EVM chain 2. **processing**: Workflow initiated for redemption 3. **burning**: Sending native tokens to destination address 4. **completed**: Native tokens sent to destination wallet 5. **failed**: Error occurred during processing (see errorMessage) ### Pagination Use `limit` and `offset` for pagination: ```bash # First page (orders 0-19) curl "https://api.universal.xyz/issuance-redemption/orders?limit=20&offset=0" # Second page (orders 20-39) curl "https://api.universal.xyz/issuance-redemption/orders?limit=20&offset=20" # Third page (orders 40-59) curl "https://api.universal.xyz/issuance-redemption/orders?limit=20&offset=40" ``` **Pagination Response Fields**: * `limit`: Requested limit * `offset`: Current offset * `total`: Total number of orders matching filters * `hasMore`: Boolean indicating if more results exist ### Filtering #### Filter by Type ```bash # Only mint orders curl "https://api.universal.xyz/issuance-redemption/orders?type=mint" # Only burn orders curl "https://api.universal.xyz/issuance-redemption/orders?type=burn" ``` #### Filter by Status ```bash # Only completed orders curl "https://api.universal.xyz/issuance-redemption/orders?status=completed" # Only pending orders curl "https://api.universal.xyz/issuance-redemption/orders?status=pending" # Only failed orders curl "https://api.universal.xyz/issuance-redemption/orders?status=failed" ``` #### Combine Filters ```bash # Completed mint orders curl "https://api.universal.xyz/issuance-redemption/orders?type=mint&status=completed&limit=50" ``` ### Polling for Updates To monitor order progress, poll the endpoint periodically: ```javascript async function waitForOrderCompletion(orderId) { while (true) { const response = await fetch(`https://api.universal.xyz/issuance-redemption/orders?limit=100`, { headers: { Authorization: `Bearer ${jwtToken}`, }, }); const data = await response.json(); const order = data.data.orders.find((o) => o.id === orderId); if (!order) { throw new Error('Order not found'); } if (order.status === 'completed') { console.log('Order completed!', order.transactionHash); return order; } if (order.status === 'failed') { throw new Error(`Order failed: ${order.errorMessage}`); } // Poll every 10 seconds await new Promise((resolve) => setTimeout(resolve, 10000)); } } ``` **Recommended Polling Intervals**: * Pending/Processing orders: Every 10-30 seconds * Completed/Failed orders: No polling needed ### Error Messages Common error messages in `errorMessage` field: #### Mint Errors | Error Message | Cause | Resolution | | --------------------------------- | ------------------------------ | --------------------------------- | | `Insufficient deposit amount` | Amount below minimum threshold | Send more tokens | | `Wallet address inactive` | User wallet deactivated | Contact support | | `Blockchain confirmation timeout` | Source chain congestion | Wait for retry or contact support | | `Minting contract error` | Smart contract issue | Contact support | #### Burn Errors | Error Message | Cause | Resolution | | ----------------------------------------- | ------------------------------ | -------------------------------- | | `Insufficient balance` | Not enough uAssets in wallet | Verify wallet balance | | `Amount below minimum burn` | Amount below minimum threshold | Increase burn amount | | `Invalid destination address` | Malformed destination address | Update burn wallet configuration | | `Transaction failed on destination chain` | Blockchain issue | Contact support | ### Best Practices 1. **Poll Responsibly**: Don't poll more frequently than every 5-10 seconds 2. **Handle All Statuses**: Implement logic for all possible order statuses 3. **Store Order IDs**: Save order IDs for future reference and reconciliation 4. **Monitor Failed Orders**: Alert on failed orders and investigate errorMessage 5. **Use Pagination**: For wallets with many orders, paginate results efficiently 6. **Filter Appropriately**: Use filters to reduce response size and improve performance ### Next Steps * [Mint API](/docs/developers/integrate-the-issuance-and-redemption-universal-api/mint-api.md) - Create mint operations that generate orders * [Burn API](/docs/developers/integrate-the-issuance-and-redemption-universal-api/burn-api.md) - Create burn operations that generate orders * [Examples](/docs/developers/integrate-the-issuance-and-redemption-universal-api/examples.md) - Complete order tracking examples --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.universal.xyz/docs/developers/integrate-the-issuance-and-redemption-universal-api/orders-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.