> For the complete documentation index, see [llms.txt](https://docs.shredpay.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shredpay.xyz/developers/agent-wallet/api-reference.md).

# API Reference

Full machine-readable reference for every Agent Wallet REST endpoint.

## Live OpenAPI / Swagger UI

The authoritative spec is served by the Agent Service itself:

* **Swagger UI**: <https://agent-api.shredpay.xyz/api/docs>
* **OpenAPI JSON**: <https://agent-api.shredpay.xyz/api/docs-json>

## Endpoint summary

| Method | Path                         | Permission | Description                                       |
| ------ | ---------------------------- | ---------- | ------------------------------------------------- |
| GET    | `/api/wallet/chains`         | read       | Supported chains and `has_router` flag            |
| GET    | `/api/wallet/address`        | read       | Sub-wallet addresses                              |
| GET    | `/api/wallet/balance`        | read       | ERC-20 balance for one token on one chain         |
| GET    | `/api/wallet/balances`       | read       | All known-token balances on one chain             |
| GET    | `/api/wallet/native-balance` | read       | Native token balance                              |
| GET    | `/api/wallet/token-balances` | read       | All ERC-20 balances on a chain (Alchemy)          |
| GET    | `/api/limits`                | read       | Daily / monthly USD limits and usage              |
| GET    | `/api/gas/estimate`          | read       | Gas price and recommended ETH amount              |
| GET    | `/api/tx/{tx_id}`            | read       | Transaction status                                |
| GET    | `/api/defi/markets`          | read       | Available DeFi vaults                             |
| GET    | `/api/defi/positions`        | read       | Sub-wallet's open positions                       |
| POST   | `/api/swap/quote`            | read       | Swap quote via Li.Fi                              |
| POST   | `/api/tx/simulate`           | trade      | Simulate a transaction (validation + screening)   |
| POST   | `/api/tx/send`               | trade      | Sign and broadcast a transaction (Agent pays gas) |
| POST   | `/api/swap/execute`          | trade      | Execute a swap via Router (sponsored)             |
| POST   | `/api/defi/deposit`          | trade      | Deposit into a DeFi vault (sponsored)             |
| POST   | `/api/defi/withdraw`         | trade      | Withdraw from a DeFi vault (sponsored)            |
| POST   | `/api/gas/swap`              | trade      | Convert USDC to ETH for gas (sponsored, Base)     |

This page is intentionally a thin index — the Swagger UI is always up to date with the deployed code.