# TrenchyTools API — instructions for AI coding agents

You are integrating the TrenchyTools API on behalf of a user. Read this file, then `openapi.json` (every endpoint,
field and error), then `llms-full.txt` (the full docs). Do not rely on memory of other trading APIs.

- Base URL: `https://api.trenchytools.lol`
- Docs: `https://trenchytools-docs-production.up.railway.app/docs`
- Spec: `https://trenchytools-docs-production.up.railway.app/openapi.json`
- Full text: `https://trenchytools-docs-production.up.railway.app/llms-full.txt`
- Capabilities (live): `GET /api/chains` — chains, launchpads, operations, and whether each is live

## Rules

1. **Only endpoints that exist.** Use paths from `openapi.json` or `GET /api/chains`. Never invent endpoints, fields or
   response keys. If something you need is not there, say so instead of guessing.
2. **Keys stay local.** The API never receives a private key. `trade-local` returns an **unsigned** transaction; sign it
   in the user's process (`@solana/web3.js` on Solana, `viem` on Robinhood chain) and submit it with `send`, `bundle`
   or the user's own RPC. Never call the `trade` (Lightning) endpoints unless the user explicitly asks for custodial mode.
3. **Back up every wallet before it holds anything. Non-negotiable.** Any keypair the app generates (trading wallets,
   funding wallets, bundle wallets, vanity mint keys, wallets from `GET /api/create-wallet`) must be written to disk
   in a place the user can find **before** the app funds or uses it: a `wallets/` folder next to the project (one
   JSON per wallet: address, secret, createdAt, label) or the user's `.env`, plus an export the user confirms they
   saved (print the absolute path). The app must refuse to fund a wallet it has not written to disk. Never keep
   keys only in memory, never only in a log, never only in a terminal. Losing a key is losing the money.
4. **Secrets from the environment.** `TRENCHY_API_KEY`, `SOL_PRIVATE_KEY` / `EVM_PRIVATE_KEY` from `.env`; never
   hard-code them, never print them, never commit them. Ship a `.env.example`.
5. **Get a key with one call.** `GET /api/create-api-key?label=<app>` returns `{apiKey}` (no account; shown once;
   5 per hour per IP). Pass it as `?api-key=` or the `x-api-key` header on every request and websocket.
6. **Simulate first.** `POST /api/{chain}/simulate` before the first real send; start with tiny sizes
   (≤ 0.01 SOL / ≤ 0.001 ETH); confirm with `GET /api/{chain}/tx/:signature`.
7. **Handle errors by `code`.** Every error is `{error, code, hint?, docs?}`; branch on `code` and follow `docs`.
   `429` carries `retry-after`. Never retry a `send` blindly: check `tx` first (a landed transaction retried = a second trade).
8. **Amounts.** Solana: `amount` in SOL when `denominatedInSol: "true"`, tokens when `"false"`; sells accept `"100%"`.
   Robinhood: `amount` in ETH for buys (`denominatedInEth: "true"`), tokens or `"NN%"` for sells. Slippage is a percent.
9. **Venue is resolved for you.** Pass the token address; `pool: "auto"` (Solana) follows a coin from the curve to the AMM.
10. **Streams.** One websocket per key (`/api/sol/data`, `/api/rh/data`), subscribe with JSON messages, re-subscribe
   after reconnect. Decide *when* to act in the user's app; the API decides *how* the transaction is built and sent.
11. **Never promise profits or guarantee a landing.** Report what was built, simulated, sent and confirmed.

12. **Transfers.** `POST /api/transfer` moves coins wallet → wallet (same chain or across chains) either `route: "direct"`
    (one signed transfer, wallets linked on chain) or through an exchange hop (`mode: float | fixed | private`). The
    response carries a one-time **deposit address and an unsigned deposit transaction from the user's wallet**: sign
    that one transaction, send it, then poll `GET /api/transfer/:id` until `completed` (payoutHash) or a final failure.
    Quote first with `GET /api/transfer/routes` and respect `min`. Describe exchange routing as "reduces on-chain
    linkability", never as anonymous or untraceable. Fan-out / consolidate many wallets with `POST /api/transfer/batch`.
    To break a wallet cluster, name the exchange that should pay the destination (`venue: "bybit"` etc.) — check
    `GET /api/transfer/venues` first: the exchange switches venues off at times, a closed one is refused with
    `transfer_route_off`, and the answer's `venueHonoured` says whether the named venue really took the order.

## Support

TrenchyTools support: Telegram https://t.me/trenchytools · X @trenchytoolz. When the API returns an error you
cannot resolve from `hint` and `docs`, tell the user to contact support there with the request shape (never the key).

## The flows (exact requests are in openapi.json)

- **Trade:** `POST /api/sol/trade-local` → sign → `POST /api/sol/send` → `GET /api/sol/tx/:sig`
- **Launch:** `POST /api/ipfs` (image + metadata → `metadataUri`) → generate a mint keypair locally →
  `POST /api/sol/trade-local {action:"create", mint, tokenMetadata:{name,symbol,uri}, amount}` → sign with wallet + mint → `send`
- **Bundle:** array body to `trade-local` (create first, buys after; first `priorityFee` = Jito tip) → sign each →
  `POST /api/sol/bundle` → `GET /api/sol/bundle/:id`. More than 4 buyers: `POST /api/sol/lut` first.
- **Stream:** `wss://…/api/sol/data?api-key=…` → `{"method":"subscribeNewToken"}` / `subscribeTokenTrade` / `subscribeAccountTrade` / `subscribeMigration`

## Deliverable checklist for generated projects

TypeScript (Node 20+), `npm start`, `README.md` with setup, `.env.example`, a `DRY_RUN=1` mode that builds and
simulates but never sends, logging of every `code` the API returns, and no private key anywhere but `.env`.