> 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/transactions.md).
# Transactions
API endpoints for managing transactions in the PayID platform
These endpoints enable users to initiate transactions for sending tokens to PayID recipients or wallet addresses. Also they provide users with the ability to retrieve their transaction activity history.
## Initialize a transaction
> Initialize a transaction for sending tokens to a PayID recipient or wallet address.\
> \
> \## Token & Network Compatibility\
> \
> Only specific token and network combinations are supported. Currently supported:\
> \
> \*\*Tokens\*\*: USDT, USDC, ETH, BNB, POL\
> \
> \*\*Networks\*\*: ETH, POL, OP, BNB, BASE\
> \
> \*\*Unsupported combinations\*\*:\
> \- POL token on OP network\
> \- BNB token on OP network\
> \- USDT token on BASE network\
> \- BNB token on BASE network\
> \- POL token on BASE network\
> \
> \## ERC20 Token Approvals\
> \
> For ERC20 tokens (USDT, USDC), when the user has insufficient token allowance, an \`approveTx\` will be included in the response.\
> The client must execute this approval transaction first, then execute the main transaction.\
> \
> Native tokens (ETH, BNB, POL) do not require approval transactions.\
> \
> \## Route and Swap Logic\
> \
> When sending to a PayID that has routes configured, automatic token swapping may occur based on the route settings.\
> In such cases, fee information will be included in the response.
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Transactions","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"}},"schemas":{"TransactionInitialize":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"token":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"]},"network":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"]},"tx":{"type":"object","properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"}}},"fees":{"type":"object","properties":{"applicationFee":{"type":"number","nullable":true},"protocolFee":{"type":"number","nullable":true},"bridgeFee":{"type":"number","nullable":true}}},"approveTx":{"type":"object","nullable":true,"description":"When sending ERC20 tokens (such as USDT, USDC), this transaction must be executed first to approve the token spending.\nThis field is only included when the user has insufficient token allowance for the transaction.\nThe client must execute this approval transaction first, then execute the main transaction.\n\nNative tokens (like ETH, BNB, POL) do not require approval, so this field will be null in those cases.\n","properties":{"to":{"type":"string","description":"Token contract address"},"data":{"type":"string","description":"Approval transaction data (encoded approve function call)"},"chainId":{"type":"integer","description":"Chain ID for the approval transaction"}}}}},"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":{"/transactions":{"post":{"summary":"Initialize a transaction","description":"Initialize a transaction for sending tokens to a PayID recipient or wallet address.\n\n## Token & Network Compatibility\n\nOnly specific token and network combinations are supported. Currently supported:\n\n**Tokens**: USDT, USDC, ETH, BNB, POL\n\n**Networks**: ETH, POL, OP, BNB, BASE\n\n**Unsupported combinations**:\n- POL token on OP network\n- BNB token on OP network\n- USDT token on BASE network\n- BNB token on BASE network\n- POL token on BASE network\n\n## ERC20 Token Approvals\n\nFor ERC20 tokens (USDT, USDC), when the user has insufficient token allowance, an `approveTx` will be included in the response.\nThe client must execute this approval transaction first, then execute the main transaction.\n\nNative tokens (ETH, BNB, POL) do not require approval transactions.\n\n## Route and Swap Logic\n\nWhen sending to a PayID that has routes configured, automatic token swapping may occur based on the route settings.\nIn such cases, fee information will be included in the response.\n","tags":["Transactions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId","amount","token","network"],"properties":{"userId":{"type":"string","format":"uuid","description":"ID of the user initiating the transaction"},"amount":{"type":"number","format":"float","description":"Amount to send (must be a positive number)"},"token":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"],"description":"Token to send"},"network":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"],"description":"Network to use for the transaction"},"recipientPayId":{"type":"string","description":"PayID of the recipient (either recipientPayId or walletAddress is required, but not both)"},"walletAddress":{"type":"string","description":"Wallet address of the recipient (either recipientPayId or walletAddress is required, but not both)"},"message":{"type":"string","maxLength":280,"description":"Optional message to include with the transaction (max 280 characters)"}}}}}},"responses":{"200":{"description":"Transaction initialized successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"$ref":"#/components/schemas/TransactionInitialize"},"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":"Recipient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get user transaction activities
> Get transaction activities for a specific user with pagination.\
> \
> This endpoint returns both incoming (RECEIVE) and outgoing (SEND) transactions\
> for the specified user, sorted by creation date in descending order (newest first).\
> \
> The response includes detailed information about each transaction, including\
> amounts, fees, and related route information when applicable.
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Transactions","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"}},"schemas":{"TransactionActivity":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["SEND","RECEIVE"]},"amount":{"type":"number","format":"float"},"token":{"type":"string"},"network":{"type":"string"},"status":{"type":"string","enum":["PENDING","COMPLETED","FAILED"]},"txHash":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","properties":{"totalCount":{"type":"integer"},"totalPages":{"type":"integer"},"currentPage":{"type":"integer"},"pageSize":{"type":"integer"}}},"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":{"/transactions/users/{userId}/activities":{"get":{"summary":"Get user transaction activities","description":"Get transaction activities for a specific user with pagination.\n\nThis endpoint returns both incoming (RECEIVE) and outgoing (SEND) transactions\nfor the specified user, sorted by creation date in descending order (newest first).\n\nThe response includes detailed information about each transaction, including\namounts, fees, and related route information when applicable.\n","tags":["Transactions"],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID of the user to get activities for"},{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number for pagination"},{"name":"pageSize","in":"query","schema":{"type":"integer","default":10},"description":"Number of items per page"}],"responses":{"200":{"description":"Transaction activities retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"type":"object","properties":{"activities":{"type":"array","items":{"$ref":"#/components/schemas/TransactionActivity"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid input parameters","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 data","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"}}}}}}}}}
```
## The Error object
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Transactions","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 - Transactions","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 TransactionInitialize object
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Transactions","version":"1.0.0"},"components":{"schemas":{"TransactionInitialize":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"token":{"type":"string","enum":["USDT","USDC","ETH","BNB","POL"]},"network":{"type":"string","enum":["ETH","POL","OP","BNB","BASE"]},"tx":{"type":"object","properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"}}},"fees":{"type":"object","properties":{"applicationFee":{"type":"number","nullable":true},"protocolFee":{"type":"number","nullable":true},"bridgeFee":{"type":"number","nullable":true}}},"approveTx":{"type":"object","nullable":true,"description":"When sending ERC20 tokens (such as USDT, USDC), this transaction must be executed first to approve the token spending.\nThis field is only included when the user has insufficient token allowance for the transaction.\nThe client must execute this approval transaction first, then execute the main transaction.\n\nNative tokens (like ETH, BNB, POL) do not require approval, so this field will be null in those cases.\n","properties":{"to":{"type":"string","description":"Token contract address"},"data":{"type":"string","description":"Approval transaction data (encoded approve function call)"},"chainId":{"type":"integer","description":"Chain ID for the approval transaction"}}}}}}}}
```
## The TransactionActivity object
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Transactions","version":"1.0.0"},"components":{"schemas":{"TransactionActivity":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["SEND","RECEIVE"]},"amount":{"type":"number","format":"float"},"token":{"type":"string"},"network":{"type":"string"},"status":{"type":"string","enum":["PENDING","COMPLETED","FAILED"]},"txHash":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}
```
## The Pagination object
```json
{"openapi":"3.0.0","info":{"title":"PayID REST API - Transactions","version":"1.0.0"},"components":{"schemas":{"Pagination":{"type":"object","properties":{"totalCount":{"type":"integer"},"totalPages":{"type":"integer"},"currentPage":{"type":"integer"},"pageSize":{"type":"integer"}}}}}}
```
---
# 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/transactions.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.