# Ten Thousand Tokens Agent Guide

This is the canonical entrypoint for agents integrating with Ten Thousand Tokens.

Ten Thousand Tokens exposes non-custodial resources for launched-token discovery,
quotes, unsigned transaction building, trade history, wallet inventory, and
secondary NFT acquisition links.

## Start Here

- API manifest: `/api/agents/manifest`
- Token dataset: `/api/agents/tokens`
- Token metadata: `/api/agents/tokens/{tokenIdOrAddress}`
- Token trades: `/api/agents/tokens/{tokenIdOrAddress}/trades`
- Wallet inventory: `/api/agents/wallet/{address}`
- Quote token trade: `POST /api/agents/trade/quote`
- Build token trade: `POST /api/agents/trade/build`
- Check transaction: `/api/agents/tx/{hash}`
- OpenSea collection: `https://opensea.io/collection/ten-thousand-tokens`

## Execution Model

The API never holds keys, signs transactions, custodies funds, or submits trades.
Write endpoints return unsigned EIP-1193-style transaction requests. The agent,
user wallet, or wallet provider must sign and broadcast them.

## Supported Actions

- Discover launched tokens and market data.
- Read a token by token id or token contract address.
- Read recent indexed swaps for a token.
- Quote a buy or sell against the Ten Thousand Tokens Uniswap v4 pool.
- Build unsigned Universal Router transactions for token buys.
- Build ERC20 approval, Permit2 typed data, and Universal Router transactions
  for token sells.
- Build unsigned fee-claim transactions.
- Build unsigned burn-and-launch transactions for wallets that acquired NFTs on
  OpenSea.
- Build unsigned token buyback transactions where available.
- Link agents to OpenSea for secondary NFT buys.

## Not Supported

- Minting. Minting is over.
- Server-side custody or backend private-key execution.
- Guaranteed routing, guaranteed liquidity, or guaranteed indexing latency.
- Direct OpenSea order execution through this app.

## Trade Flow

1. Load `/api/agents/manifest`.
2. Load `/api/agents/tokens` or a specific token endpoint.
3. Call `POST /api/agents/trade/quote`.
4. Call `POST /api/agents/trade/build`.
5. If selling and approval is required, sign and broadcast the approval first.
6. If selling and Permit2 signature is required, sign the returned typed data,
   then call the build endpoint again with `permit2Signature`.
7. Sign and broadcast the returned router transaction.
8. Poll `/api/agents/tx/{hash}` and token trade history until indexed.

## Quote Example

```json
{
  "side": "buy",
  "token": "1",
  "amountInWei": "10000000000000000",
  "slippageBps": 100
}
```

## Build Example

```json
{
  "side": "buy",
  "token": "1",
  "from": "0x0000000000000000000000000000000000000000",
  "amountInWei": "10000000000000000",
  "slippageBps": 100
}
```

All wei, calldata, hashes, and contract addresses are strings.