> 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/integration-best-practices.md).

# Integration Best Practices

This guide outlines best practices for developers integrating with the Reveel PayID API. Following these principles will help ensure a reliable, secure, and scalable integration.

### 1. Authentication

* Always include your API key in the Authorization header:

  ```
  Authorization: Bearer your-api-key
  ```
* Store API keys securely in environment variables, never in frontend code or public repositories
* Implement key rotation mechanisms if your backend supports it
* Use proper error handling for 401 responses to trigger re-authentication flows

### 2. Token and Network Compatibility

* Only use the supported tokens: `USDT`, `USDC`, `ETH`, `BNB`, `POL` - along with native tokens of respective chains.
* Only use the supported networks: `ETH`, `POL`, `OP`, `BNB`, `BASE`
* Be aware of 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

### 3. Transaction Handling

* For ERC20 tokens (USDT, USDC), always check for `approveTx` in the response
* If `approveTx` is present, execute this transaction first before the main transaction
* Implement proper error handling for transaction states (pending, completed, failed)
* Add client-side idempotency keys to prevent accidental duplicate transactions
* When sending to a PayID, be prepared to handle route-based swaps and associated fees

### 4. Error Handling

* All API responses follow a consistent format with `success` flag
* Error responses include detailed information in the `error` object:

  ```json
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid input data",
      "details": {
        "errors": [
          {
            "path": ["userId"],
            "message": "userId is required"
          }
        ]
      }
    }
  }
  ```
* Implement specific handling for common errors:
  * 400: Client-side validation errors
  * 401: Authentication failures
  * 404: Resource not found
  * 409: Conflicts (e.g., route conflicts, PayID already taken)
  * 500: Server errors (may be retried with backoff)

### 5. Pagination

* When fetching transaction activities, always use pagination parameters:
  * `page` (default: 1): Page number
  * `pageSize` (default: 10): Number of items per page
* Implement UI for pagination controls or auto-load mechanisms
* Use the pagination metadata returned in the response for accurate UI:

  ```json
  "pagination": {
    "totalCount": 25,
    "totalPages": 3,
    "currentPage": 1,
    "pageSize": 10
  }
  ```

### 6. Network Resilience

* Implement retry logic with exponential backoff for 5xx errors and timeouts
* Do not retry on 4xx errors (except possibly 429 Too Many Requests)
* Recommended backoff strategy:
  * Initial delay: 1 second
  * Maximum retries: 3
  * Exponential factor: 2 (1s, 2s, 4s)
* Add circuit breakers to prevent cascading failures during API outages

### 7. Monitoring and Logging

* Log all API requests with relevant details:
  * Endpoint path
  * HTTP method
  * Response status code
  * Error messages (without sensitive data)
  * Response times
* Track transaction success rates for user analytics
* Implement health checks to detect API availability issues

### 8. Security Considerations

* Validate wallet addresses on the client side before submission
* Never log full transaction data that might contain sensitive information
* Implement rate limiting in your client applications to prevent abuse
* For PayID integrations, validate PayID format before submission to reduce errors

### 9. Performance Optimization

* Cache frequently accessed data (user lists, routes)
* Implement conditional fetching based on UI state
* Use local storage or state management to reduce redundant API calls
* Prefetch anticipated data when appropriate (e.g., user routes before transaction)

### 10. API Evolution

* The Reveel API uses versioned endpoints (`/v1/transactions`)
* Monitor for deprecation notices and new versions
* Design your integration to easily accommodate API changes by using abstraction layers
* Subscribe to developer notifications if available to stay current with changes

### 11. Content Headers

* Always include proper headers for all requests:

  ```
  Accept: application/json
  Content-Type: application/json  // For requests with bodies
  ```
* Validate response content types to ensure you're receiving JSON data
* Handle unexpected content types gracefully (e.g., HTML error pages)


---

# 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/integration-best-practices.md?ask=<question>&goal=<endgoal>
```

`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.