# YEET for *agents.*

An MCP endpoint for coding agents: Claude Code, Codex or any MCP client. There are two ways to trade. The first: the person approves the agent once in the browser, and the agent signs with the person's own YEET wallet, so ChatGPT and the agent share one wallet and one portfolio. The second: the agent trades with its own key, from a budget the person sends it.

## Connect

- **Endpoint:** `https://mcp.yeet.win`, MCP over Streamable HTTP.
- **Sign-in:** standard MCP OAuth. The person signs in with their YEET account in the browser, once per connection.
- **Results:** plain JSON in every tool result. There are no cards and no widgets.
- **Settlement:** every trade is a NEAR Intents message in the NEAR Intents ledger (`intents.near`). It settles in one ledger call, or nothing moves.
- **Fees:** YEET charges no fee. The ledger's own cost is in the quote.

The ChatGPT app keeps its own endpoint. A ChatGPT connection cannot call the agent tools, and an agent connection cannot call the ChatGPT tools.

Claude Code:

```sh
claude mcp add --transport http yeet https://mcp.yeet.win
```

Then run `/mcp` inside Claude Code, pick `yeet` and sign in.

Codex:

```sh
codex mcp add yeet --url https://mcp.yeet.win
codex mcp login yeet
```

Or in `~/.codex/config.toml`:

```toml
[mcp_servers.yeet]
url = "https://mcp.yeet.win"
```

Any other MCP client works the same way: it registers itself with a loopback redirect (`http://127.0.0.1:<port>/...` or `http://localhost:<port>/...`), opens the sign-in page in the browser, and receives the code on its own machine. Agent connections accept loopback redirects only.

Start with `agent_how_it_works`, then `agent_overview`. Then pick one of the two ways below. Every trade names its way in `account`: `"owner"` for the first, `"agent"` (the default) for the second.

## Way 1: the same wallet

The agent signs with the person's own YEET wallet, the one they trade with in ChatGPT. ChatGPT and the agent share one wallet and one portfolio. The agent gets no key of its own and no YEET secret. The signature comes from the person's wallet, so YEET's server is not on the signing path: it receives the finished signature only.

Approval lets the agent sign anything with your wallet until you revoke it. YEET's trade limits apply to trades sent through this route only.

### Approve the agent once

The approval uses Privy's CLI and agent access (YEET wallets are Privy wallets) through [`examples/agent-access`](https://github.com/chaintail/yeet-win/tree/main/examples/agent-access), Node 20 or newer:

```sh
cd examples/agent-access
npm ci
export YEET_PRIVY_APP_ID=<the YEET Privy app id>
node src/cli.mjs login
```

1. `login` prints a link to `https://mcp.yeet.win/approve` and a short code.
2. The person opens the link, signs in with their YEET account, checks that the page shows the same code, and presses Approve.
3. `node src/cli.mjs wallets` lists the wallets the agent may use. The Solana wallet signs the trades. Its ledger account is the 64 hex characters of its 32-byte public key.

Only approve a code your own agent printed.

### Trading

1. `agent_quote` with `account: "owner"`, `side`, `coins` and `amount_usdc` (buy) or `percent` (sell). It returns `quote_id`.
2. `agent_prepare_trade` with `quote_id` and `account: "owner"`. It checks the limits and returns `request`: `message` (the unsigned NEAR Intents `token_diff`, standard `raw_ed25519`), `request_id`, `signer_id`, `gives`, `receives` and `sign_before`.
3. The agent checks that `signer_id` is the ledger account of the person's Solana wallet, then has the wallet sign the exact UTF-8 bytes of `message`: `node src/cli.mjs sign-message <message as base64>` prints the signature as base64.
4. `agent_submit_signature` with `request_id` and that signature.
5. `agent_trade_status` with `trade_id` until `status` is `success` or `failed`.

From Node, the same signature:

```js
import {openSession} from './examples/agent-access/src/agent.mjs';
const wallet = await openSession({appId: process.env.YEET_PRIVY_APP_ID});
const {signature} = await wallet.signMessage(Buffer.from(request.message, 'utf8').toString('base64'));
```

[`examples/agent-mcp`](https://github.com/chaintail/yeet-win/tree/main/examples/agent-mcp) does all of this with `--account owner`. It runs in dry mode by default: it quotes, opens no wallet and signs nothing. `--live` prepares, checks `signer_id`, signs and submits.

### Revoke it

- **Everywhere:** open `https://mcp.yeet.win/approve`, sign in, and press **Revoke** next to the agent under **Agents with access**. The agent can still sign for at most 15 minutes with the access it already holds.
- **On this computer:** `node src/cli.mjs logout` forgets this agent's login here. The approval stays listed on the page until it is revoked there.

## Way 2: its own key and a budget

The agent trades with its own ed25519 key, from a budget the person sends it. The person approves the budget once. The agent cannot spend more. This is the default: `account: "agent"`, or `account` left out.

### Its key

- The agent generates an ed25519 key pair on its own machine and keeps the private key there. YEET never asks for it and never holds it.
- The agent's account in the NEAR Intents ledger is the implicit account of its public key: the 64 hex characters of the 32 public key bytes. That account is the agent's balance.
- One key per connection. A key that is already linked to another connection is refused, and so is the key of any YEET wallet. Make a key for this agent only.
- A key is sent as `ed25519:<base58>`, plain base58, or 64 hex.

Generate one with Node:

```js
import {generateKeyPairSync} from 'node:crypto';
const {publicKey, privateKey} = generateKeyPairSync('ed25519');
const raw = publicKey.export({format: 'jwk'}).x;           // base64url, 32 bytes
const hex = Buffer.from(raw, 'base64url').toString('hex');  // the ledger account and public_key
```

### The budget

1. The agent calls `agent_register_key` with its public key and a budget in USDC.
2. The result carries `budget_url`. The agent gives that link to the person.
3. The person opens it, signs in to YEET, and sees the amount and the words "agent budget". They approve ONE ledger transfer of that amount from their own YEET balance to the agent's account. Their own wallet signs it.
4. `agent_overview` then reads `state: "active"` and shows the balance.

- A budget link stays open for 24 hours.
- Only the signed-in owner of the YEET account can open it.
- The page refuses any message that is not exactly one transfer of the stated amount to the stated agent account.
- What the agent already holds plus the new budget stays within the budget cap. A top-up is a new `agent_register_key` call with the same key. A new link closes the one before it.
- A budget is paid in Solana USDC from the person's YEET balance.

### Trading

1. `agent_quote` with `side: "buy"`, `coins` and `amount_usdc`, or `side: "sell"`, `coins` and `percent`. It returns `quote_id`.
2. `agent_prepare_trade` with `quote_id`. It checks the limits and returns `request`: `message` (the unsigned NEAR Intents `token_diff`, standard `raw_ed25519`), `request_id`, `gives`, `receives` and `sign_before`.
3. The agent signs the exact UTF-8 bytes of `message`, with no prefix, using its ed25519 key.
4. `agent_submit_signature` with `request_id` and the signature (base64, 88 characters, or hex, 128 characters). YEET checks the signature against the key, simulates the message and settles it.
5. `agent_trade_status` with `trade_id` until `status` is `success` or `failed`.

Signing with Node:

```js
import {sign} from 'node:crypto';
const signature = sign(null, Buffer.from(request.message, 'utf8'), privateKey).toString('base64');
```

To end, `agent_return_budget` returns the unsigned transfer of one token of the balance (USDC first) to the owner's YEET ledger account, the only receiver it can name. The agent signs it and sends it with `agent_submit_signature`. While `remaining_tokens` is above 0, it calls `agent_return_budget` again after the transfer settles.

### What the agent cannot do on this way

- **Touch the person's wallet.** The person's own wallet signs the budget transfer on the YEET page. The agent never sees their key.
- **Spend more than the budget.** The agent's account holds only what the person sent to it.
- **Pay anyone else.** A return names the owner's YEET ledger account as the only receiver. Trades settle inside the agent's own account.
- **Open a budget link for the person.** Only the signed-in owner can approve it.

[`examples/agent-mcp`](https://github.com/chaintail/yeet-win/tree/main/examples/agent-mcp) is a small Node script that generates a key, signs in, registers the key, prints the budget link, then quotes and trades within its budget. It runs in dry mode by default: it quotes and prints what it would sign, and moves nothing.

## Tools

| Tool | Parameters | What it does |
|---|---|---|
| `agent_overview` | none | The registered key, the state (`not_registered`, `awaiting_budget`, `active`), the balance, the limits, the next step, and `budget_url` while one is open. |
| `agent_how_it_works` | none | How keys, the budget, signing and the limits work. Reads no account data. |
| `agent_register_key` | `public_key` (string), `budget_usdc` (decimal string, e.g. `"20"`) | Way 2: registers the key for this connection and returns `budget_url` for the person. |
| `agent_balance` | none | The agent's ledger balance: USDC and the listed coins. |
| `agent_quote` | `side` (`buy` or `sell`), `coins` (1 to 5 symbols), `amount_usdc` (buy), `percent` (sell, 1 to 100, default 100), `account` (`owner` or `agent`, default `agent`) | A firm quote. A buy splits `amount_usdc` evenly over the coins. Returns `quote_id`. |
| `agent_prepare_trade` | `quote_id` (`p_` id), `revision` (optional integer), `account` (`owner` or `agent`, default `agent`) | Checks the limits and returns the unsigned message, the account that signs it (`signer_id`) and `request_id`. |
| `agent_submit_signature` | `request_id`, `signature` (base64 or hex) | Hands over the signature for a trade or a return. |
| `agent_trade_status` | `trade_id` (`t_` id) | One trade's status and what it received. |
| `agent_positions` | none | USDC, the held coins with their USD value, the last 5 trades and what is left of today's limit. |
| `agent_return_budget` | none | Way 2: the unsigned transfer of one token back to the owner's YEET ledger account. `remaining_tokens` says whether to call it again. |

The input schemas are in [`contracts/yeet-agent-tools.json`](https://github.com/chaintail/yeet-win/blob/main/contracts/yeet-agent-tools.json).

## Limits

| Limit | Value |
|---|---|
| Per buy | 10 USDC |
| Per UTC day, buys | 50 USDC |
| Budget held by one agent | 100 USDC |
| Coins per quote | 5 |

- These apply to trades sent through this endpoint, on top of the YEET account's own limits. On way 1 they do not cover anything else the approved agent signs with the wallet. The budget cap is for way 2 only.
- `agent_overview` shows the values in force under `limits`, with `spent_today_usdc` and `left_today_usdc`.
- Only the coins in `limits.coins` can be traded.
- Sells are not capped and not counted. They turn coins back into USDC inside the same account.
- The caps are set on the server and checked at quote and again at prepare. An agent cannot raise them.
- Agent trades earn no XP, do not spin the wheel and do not rank on the leaderboards.

## Errors

Every refusal is a tool error whose text is JSON:

```json
{"error": "LIMIT_EXCEEDED", "message": "An agent trade is at most 10 USDC.", "retryable": false}
```

`message` is a sentence the agent can relay to the person. A refusal may add `correct_url`, `coins` or `limits`.

### WRONG_ROUTE

The agent endpoint is for agents and the ChatGPT endpoint is for ChatGPT. A connection that calls the other one is refused with `WRONG_ROUTE`:

- at sign-in, as the OAuth error `invalid_target` whose description starts with `WRONG_ROUTE:`,
- on an MCP call, as HTTP 403 with a JSON-RPC error whose `data.error` is `WRONG_ROUTE` and whose `data.correct_url` names the right endpoint.

The fix is to connect to the URL in the message.

### Codes

- `WRONG_ROUTE`: this connection belongs to the other endpoint.
- `AGENT_NOT_REGISTERED`: way 2: call `agent_register_key` first.
- `AGENT_NOT_FUNDED`: way 2: the budget has not landed yet. The person still has to approve `budget_url`.
- `AGENT_KEY_INVALID`: the public key is not a valid ed25519 key.
- `AGENT_KEY_TAKEN`: the key is linked to another connection.
- `AGENT_KEY_LINKED`: this connection already has an active key. Return the budget first, or connect as a new agent.
- `LIMIT_EXCEEDED`: over a per-trade, daily or budget limit.
- `QUOTE_NOT_FOUND`: unknown `quote_id` for this agent.
- `REQUOTE_REQUIRED`: the quote is stale. Quote again.
- `REQUEST_EXPIRED`: `sign_before` has passed. Prepare again.
- `REQUEST_CLOSED`: the request was already submitted or closed.
- `SIGNATURE_INVALID`: the signature does not verify against the key of `signer_id`.
- `NOTHING_TO_RETURN`: the balance is empty.
- `REAUTH_REQUIRED`: the connection lacks the permission for that tool. Connect again and approve it.
- `INVALID_ARGUMENT`: a parameter is malformed. The message names it.
- `TEMPORARILY_UNAVAILABLE`: nothing moved. Try again in a minute.

The YEET account's own checks can refuse too, with the codes in [`contracts/yeet-tools.json`](https://github.com/chaintail/yeet-win/blob/main/contracts/yeet-tools.json) (`x-yeet-errors`).

On way 1, `examples/agent-access` exits with code 1 and a sentence when the approval was revoked or has ended ("Run login again"), and with code 2 on wrong usage.
