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


---

# Agent Instructions: 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:

```
GET https://developers.shredpay.xyz/agent-wallet/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.