> For the complete documentation index, see [llms.txt](https://docs.reveel.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reveel.id/api-references/routes.md).
# Routes
API endpoints for managing Routes in the PayID platform.
Routes define how incoming payments are handled, including which networks and tokens are accepted, optional token swaps, and the destination wallet for final transfers.
When creating a route, consider these important factors:
* Each route must have a unique combination of incoming networks and tokens per user.
* Certain network-token combinations are not supported (see Unsupported Combinations section).
* Users can have multiple routes with different configurations.
## Create a new route
> Create a new route for a specific user. A route defines how incoming payments should be processed.\
> Routes must have a unique combination of incoming networks and tokens per user.\
> Certain network-token combinations are not supported (see API description for details).
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Routes","version":"1.0.0"},"servers":[{"url":"https://api.reveel.id/v1","description":"Production API Server"},{"url":"https://staging-api.reveel.id/v1","description":"Staging API Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API keys are provided when a partner account is created and can be regenerated if needed.\nTo authenticate requests, include your API key in the request headers using the Bearer token format:\n`Authorization: Bearer your-api-key`\n\n## Required Permissions\n\nThe following permissions are required for the Routes endpoints:\n\n- **route:create** - Create new routes for users associated with your partner account\n- **route:read** - View routes for users associated with your partner account\n- **route:update** - Modify route information for users associated with your partner account\n- **route:delete** - Delete routes for users associated with your partner account\n"}},"schemas":{"Route":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Name of the route.\nMinimum length: 1 character\n"},"incomingWallets":{"type":"array","items":{"type":"string"}},"incomingNetworks":{"type":"array","items":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"]}},"incomingTokens":{"type":"array","items":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"]}},"swapNetwork":{"type":"string","nullable":true,"enum":["ETH","POL","OP","BNB","BASE"]},"swapToken":{"type":"string","nullable":true,"enum":["USDT","USDC","ETH","BNB","POL"]},"outgoingWallet":{"type":"string","description":"Destination wallet address where funds will be sent.\nThe system does minimal validation on this field - it only verifies it's a non-empty string.\nEnsure you're providing a valid blockchain address for the corresponding network.\n"},"userId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ValidationError":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}}}}}}}}},"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","nullable":true}}}}}}},"paths":{"/routes":{"post":{"summary":"Create a new route","description":"Create a new route for a specific user. A route defines how incoming payments should be processed.\nRoutes must have a unique combination of incoming networks and tokens per user.\nCertain network-token combinations are not supported (see API description for details).\n","tags":["Routes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId","name","incomingNetworks","incomingTokens","outgoingWallet"],"properties":{"userId":{"type":"string","format":"uuid","description":"ID of the user this route belongs to"},"name":{"type":"string","description":"Name of the route.\nMinimum length: 1 character.\n"},"incomingWallets":{"type":"array","items":{"type":"string"},"description":"List of incoming wallet addresses that can use this route.\nThe system performs minimal validation - verify addresses are valid for the corresponding blockchain.\n"},"incomingNetworks":{"type":"array","items":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"]},"description":"List of incoming networks this route supports"},"incomingTokens":{"type":"array","items":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"]},"description":"List of incoming tokens this route supports.\nNote that certain network-token combinations are not supported.\n"},"swapNetwork":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"],"nullable":true,"description":"Network to swap on (optional).\nIf provided, swapToken must also be specified.\n"},"swapToken":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"],"nullable":true,"description":"Token to swap to (optional).\nIf provided, swapNetwork must also be specified.\n"},"outgoingWallet":{"type":"string","description":"Destination wallet address where funds will be sent.\nThe system performs minimal validation - ensure you're providing a valid blockchain address \nfor the corresponding network.\n"}}}}}},"responses":{"201":{"description":"Route created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"type":"object","properties":{"route":{"$ref":"#/components/schemas/Route"}}},"meta":{"type":"object","properties":{"message":{"type":"string","description":"Status message"}}}}}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
### Unsupported Combinations
The following network - token combinations are not supported:
| Network | Token |
| ------- | ----- |
| OP | POL |
| OP | BNB |
| BASE | USDT |
| BASE | BNB |
| BASE | POL |
## Get all routes for a user
> Retrieve all routes for a specific user.
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Routes","version":"1.0.0"},"servers":[{"url":"https://api.reveel.id/v1","description":"Production API Server"},{"url":"https://staging-api.reveel.id/v1","description":"Staging API Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API keys are provided when a partner account is created and can be regenerated if needed.\nTo authenticate requests, include your API key in the request headers using the Bearer token format:\n`Authorization: Bearer your-api-key`\n\n## Required Permissions\n\nThe following permissions are required for the Routes endpoints:\n\n- **route:create** - Create new routes for users associated with your partner account\n- **route:read** - View routes for users associated with your partner account\n- **route:update** - Modify route information for users associated with your partner account\n- **route:delete** - Delete routes for users associated with your partner account\n"}},"schemas":{"Route":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Name of the route.\nMinimum length: 1 character\n"},"incomingWallets":{"type":"array","items":{"type":"string"}},"incomingNetworks":{"type":"array","items":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"]}},"incomingTokens":{"type":"array","items":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"]}},"swapNetwork":{"type":"string","nullable":true,"enum":["ETH","POL","OP","BNB","BASE"]},"swapToken":{"type":"string","nullable":true,"enum":["USDT","USDC","ETH","BNB","POL"]},"outgoingWallet":{"type":"string","description":"Destination wallet address where funds will be sent.\nThe system does minimal validation on this field - it only verifies it's a non-empty string.\nEnsure you're providing a valid blockchain address for the corresponding network.\n"},"userId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ValidationError":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}}}}}}}}},"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","nullable":true}}}}}}},"paths":{"/routes/{userId}":{"get":{"summary":"Get all routes for a user","description":"Retrieve all routes for a specific user.","tags":["Routes"],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID of the user to get routes for"}],"responses":{"200":{"description":"Routes retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"type":"object","properties":{"routes":{"type":"array","items":{"$ref":"#/components/schemas/Route"}},"count":{"type":"integer","description":"Total number of routes"}}},"meta":{"type":"object","properties":{"message":{"type":"string","description":"Status message"}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Update an existing route
> Update an existing route by ID. Supports partial updates.
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Routes","version":"1.0.0"},"servers":[{"url":"https://api.reveel.id/v1","description":"Production API Server"},{"url":"https://staging-api.reveel.id/v1","description":"Staging API Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API keys are provided when a partner account is created and can be regenerated if needed.\nTo authenticate requests, include your API key in the request headers using the Bearer token format:\n`Authorization: Bearer your-api-key`\n\n## Required Permissions\n\nThe following permissions are required for the Routes endpoints:\n\n- **route:create** - Create new routes for users associated with your partner account\n- **route:read** - View routes for users associated with your partner account\n- **route:update** - Modify route information for users associated with your partner account\n- **route:delete** - Delete routes for users associated with your partner account\n"}},"schemas":{"Route":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Name of the route.\nMinimum length: 1 character\n"},"incomingWallets":{"type":"array","items":{"type":"string"}},"incomingNetworks":{"type":"array","items":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"]}},"incomingTokens":{"type":"array","items":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"]}},"swapNetwork":{"type":"string","nullable":true,"enum":["ETH","POL","OP","BNB","BASE"]},"swapToken":{"type":"string","nullable":true,"enum":["USDT","USDC","ETH","BNB","POL"]},"outgoingWallet":{"type":"string","description":"Destination wallet address where funds will be sent.\nThe system does minimal validation on this field - it only verifies it's a non-empty string.\nEnsure you're providing a valid blockchain address for the corresponding network.\n"},"userId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ValidationError":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}}}}}}}}},"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","nullable":true}}}}}}},"paths":{"/routes/{id}":{"put":{"summary":"Update an existing route","description":"Update an existing route by ID. Supports partial updates.\n","tags":["Routes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID of the route to update"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string","format":"uuid","description":"ID of the user this route belongs to.\nThis is required as an authorization check, not as a field to update.\n"},"name":{"type":"string","description":"Name of the route.\nMinimum length: 1 character.\n"},"incomingWallets":{"type":"array","items":{"type":"string"},"description":"List of incoming wallet addresses"},"incomingNetworks":{"type":"array","items":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"]},"description":"List of incoming networks.\nIf updated, will be validated against incomingTokens for supported combinations.\n"},"incomingTokens":{"type":"array","items":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"]},"description":"List of incoming tokens.\nIf updated, will be validated against incomingNetworks for supported combinations.\n"},"swapNetwork":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"],"nullable":true,"description":"Network to swap on (optional)"},"swapToken":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"],"description":"Token to swap to (optional)"},"outgoingWallet":{"type":"string","description":"Destination wallet address.\nMinimal validation is performed - ensure it's a valid address for the network.\n"}}}}}},"responses":{"200":{"description":"Route updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"type":"object","properties":{"route":{"$ref":"#/components/schemas/Route"}}},"meta":{"type":"object","properties":{"message":{"type":"string","description":"Status message"}}}}}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - User does not have access to this route","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Route or user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Delete a route
> Delete a route by ID.
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Routes","version":"1.0.0"},"servers":[{"url":"https://api.reveel.id/v1","description":"Production API Server"},{"url":"https://staging-api.reveel.id/v1","description":"Staging API Server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API keys are provided when a partner account is created and can be regenerated if needed.\nTo authenticate requests, include your API key in the request headers using the Bearer token format:\n`Authorization: Bearer your-api-key`\n\n## Required Permissions\n\nThe following permissions are required for the Routes endpoints:\n\n- **route:create** - Create new routes for users associated with your partner account\n- **route:read** - View routes for users associated with your partner account\n- **route:update** - Modify route information for users associated with your partner account\n- **route:delete** - Delete routes for users associated with your partner account\n"}},"schemas":{"ValidationError":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}}}}}}}}},"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","nullable":true}}}}}}},"paths":{"/routes/{id}":{"delete":{"summary":"Delete a route","description":"Delete a route by ID.","tags":["Routes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID of the route to delete"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string","format":"uuid","description":"ID of the user this route belongs to"}}}}}},"responses":{"200":{"description":"Route deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"type":"object"},"meta":{"type":"object","properties":{"message":{"type":"string","description":"Status message"}}}}}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - User does not have access to this route","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Route or user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## The Error object
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Routes","version":"1.0.0"},"components":{"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","nullable":true}}}}}}}}
```
## The ValidationError object
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Routes","version":"1.0.0"},"components":{"schemas":{"ValidationError":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}}}}}}}}}}}}
```
## The Route object
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Routes","version":"1.0.0"},"components":{"schemas":{"Route":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Name of the route.\nMinimum length: 1 character\n"},"incomingWallets":{"type":"array","items":{"type":"string"}},"incomingNetworks":{"type":"array","items":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"]}},"incomingTokens":{"type":"array","items":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"]}},"swapNetwork":{"type":"string","nullable":true,"enum":["ETH","POL","OP","BNB","BASE"]},"swapToken":{"type":"string","nullable":true,"enum":["USDT","USDC","ETH","BNB","POL"]},"outgoingWallet":{"type":"string","description":"Destination wallet address where funds will be sent.\nThe system does minimal validation on this field - it only verifies it's a non-empty string.\nEnsure you're providing a valid blockchain address for the corresponding network.\n"},"userId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}
```
---
# 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.reveel.id/api-references/routes.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.