> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pesapay.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Base URLs, conventions, errors and limits for the Pesa HTTP API.

## Base URLs

| Network | Base URL |
| - | - |
| Mainnet | `https://api.pesapay.xyz` |
| Testnet | `https://api-testnet.pesapay.xyz` |

## Conventions

* **JSON** in and out. Send `content-type: application/json` with a body.
* **Amounts** are decimal integer strings in the asset's base units: 6 decimals for USDC and USDT0 on EVM chains, 7 decimals for Stellar assets. `"20000000"` on Base is 20 USDC; `"200000000"` on Stellar is 20 USDC.
* **Chains** are CAIP-2 (`eip155:8453`, `stellar:pubnet`, `stellar:testnet`). **Assets** are CAIP-19 on EVM chains and `stellar:CODE:ISSUER` on Stellar.
* **EVM addresses** are stored lower-case.
* **Times** are ISO 8601 strings in UTC.
* **Status** words follow SEP-24 and **quote** fields follow SEP-38.

## Authentication

Send `Authorization: Bearer <token>`, where the token is a SEP-10 JWT or a Privy access token. `GET /v1/routes`, the SEP-10 endpoints and the order book need none. See [Authentication](/api-reference/authentication).

## Idempotency

`POST /v1/transfers` requires an `Idempotency-Key` header. A repeat with the same key returns the same transfer. Use a new UUID for each transfer the user starts.

## Errors

Errors have a JSON body with a `message`.

| Status | Meaning |
| - | - |
| `400` | The request is malformed: a missing field, a bad address, a bad cursor |
| `401` | No token, or the token is invalid or expired |
| `403` | The token's owner may not do this, for example a deposit to another account |
| `404` | No such transfer for this owner |
| `409` | The request conflicts with the current state: a used or expired quote, a cancel after something irreversible, a duplicate submission |
| `422` | The request is valid but refused: over the daily or outstanding limit, a submission that does not match the issued action, or a transaction that is not mined yet |
| `503` | The route's chain is temporarily unavailable |

## Limits

| Limit | Value |
| - | - |
| Per transfer | \$20 |
| Started per owner per day, all routes | \$100 |
| Outstanding per owner, all routes | \$100 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.