# Bu0y — full agent reference

> Best-execution inference router. One OpenAI-compatible endpoint quotes every marketplace and fills at the cheapest source that can actually deliver.

- Site: https://bu0y.com
- API: https://api.bu0y.com
- Docs (HTML): https://bu0y.com/docs.html
- Docs (Markdown): https://bu0y.com/docs.md
- Models (live catalog): https://bu0y.com/models.html
- Short index: https://bu0y.com/llms.txt

## What it is

Inference marketplaces sell the same weights at different prices. Bu0y shops them on every request and fills from the cheapest source that clears policy. Keep your OpenAI client. Change the base URL to `https://api.bu0y.com/v1` and send a `bu0y_…` Bearer key.

Bu0y is not affiliated with the marketplaces it quotes. Nothing here is investment advice.

## Hard rules

1. **Prepaid only.** No tab. Reserve fails when the balance cannot cover the worst-case bill.
2. **Money is integer microdollars.** `$1 = 1_000_000` micros. Floating-point money never touches a balance. `costCeil` for money owed upstream, `costFloor` for what the customer is billed (rounding against Bu0y).
3. **No fill below the margin floor.** Floor is a rate, not a dollar amount. Under the floor returns **503**, not a loss-making fill.
4. **Routing is source-blind.** No special-casing a marketplace.
5. **Prompts stay off our books.** Bu0y does not store prompts or completions. Usage is billing metadata only (tokens, prices, sources, latency, status). The marketplace that fills the request still receives the prompt to run it.
6. **Credits are non-refundable.** No withdraw / cash-out path. Credits are usage rights only.

## Money and fill path

On `POST /v1/chat/completions`:

1. Authenticate (`Authorization: Bearer bu0y_…`).
2. Quote every source in parallel. A `null` quote is normal (source cannot serve), not an error.
3. Price with adaptive margin. Discard anything under `MIN_MARGIN_RATE` (15%).
4. **Reserve the worst case** against the account: input tokens + `max_tokens` (or `max_completion_tokens`) at the sell rates. Never the expected cost. Cache discounts are ignored for the reserve.
5. Execute at the cheapest survivor.
6. Settle the real bill (`costFloor`), release unused hold, enqueue what Bu0y owes the marketplace.
7. Settle completes **before** the terminal response frame. Streaming is supported; billing still settles before the stream ends.

Minimum charge covers settlement gas (~$0.002 Base / ~$0.00025 Solana equivalent in micros). A quote that cannot clear the floor after pricing returns 503.

Idempotency: send `Idempotency-Key`. Reuse returns 409 with the prior `request_id`. Completions are never stored for replay.

## Auth

### Agents (Solana wallet → key)

No human in the loop.

```
GET  /v1/auth/challenge?address=<solana_pubkey>
POST /v1/auth/keys
     body: { "message": "<from challenge>", "signature": "<base58 ed25519>", "label"?: "…" }
     → { "key": "bu0y_…", "accountId", "wallet" }
```

Then `Authorization: Bearer bu0y_…` on account, deposits, and fills.

Challenges are single-use, ~5 minute TTL. Cap: 25 active keys per wallet. Prefer a dedicated agent wallet. Do not reuse operator treasury keys.

Reference script: repo `scripts/agent-mint-key.ts`.

### Humans (passkeys → session → key)

Passkey is login only, not an API key.

1. Register / login via `/v1/auth/passkey/*` from https://bu0y.com/account.html
2. Session via cookie or `X-Bu0y-Session`
3. Mint keys: `POST /v1/account/keys` `{ "label"? }` → secret shown once
4. List: `GET /v1/account/keys` (hashes only)
5. Revoke: `POST /v1/account/keys/revoke` `{ "keyHash" }`

WebAuthn RP ID in production is `bu0y.com` (covers apex and `api.bu0y.com`).

## Funding

Credits are prepaid. `$1` USDC or card → `$1` of fill credits (1_000_000 micros). Minimum on-chain deposit: **$1**.

### Solana USDC

```
GET  /v1/deposits/solana          → { depositAddress, mint, minUsd, accountId }
POST /v1/deposits/solana/sync     → scan ATA, credit new transfers
POST /v1/deposits/solana/confirm  → { "signature": "<tx sig>" } when you already know it
```

Each account gets a **deterministic deposit address** derived from the operator treasury seed + `accountId`. Only the public address is stored. Send mainnet USDC mint `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` to that address. No memo. No wallet connect. Sync credits transfers that increase that address’s USDC balance. Idempotent on signature.

After credit, ops may sweep the ATA into the treasury. The ATA stays open for top-ups (rent paid once by the first funder).

### Base USDC

```
GET  /v1/deposits/base            → { depositAddress, mint, minUsd, accountId, chainId }
POST /v1/deposits/base/sync       → scan Transfer logs, credit new txs
POST /v1/deposits/base/confirm    → { "txHash": "0x…" }
```

Deterministic EOA from `BASE_TREASURY_KEY` + `accountId` (HMAC-secp256k1). Mint `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` on Base (8453). Idempotent on tx hash (`rail=base_usdc`).

### Stripe

```
POST /v1/deposits/stripe/checkout  { "usd": 10 }
```

Webhook credits on `checkout.session.completed`. No customer refund/payout endpoints.

## Endpoint catalog

Base: `https://api.bu0y.com`

| Method | Path | Auth | Notes |
|--------|------|------|-------|
| GET | `/health` | no | Per-source ok / degraded |
| GET | `/v1/models` | no | Union catalog, cheapest in/out per model |
| POST | `/v1/quote` | no | Free. Body: `model`, `inputTokens`, `maxOutputTokens` |
| POST | `/v1/chat/completions` | Bearer | OpenAI-compatible fill |
| GET | `/v1/harbor` | no | Retail vs Bu0y rates for the site sheet |
| GET | `/v1/stats` | no | Aggregates only |
| GET | `/v1/account` | Bearer/session | Balance micros |
| GET | `/v1/account/usage` | Bearer/session | Own usage metadata |
| GET | `/v1/account/keys` | Bearer/session | Key hashes |
| POST | `/v1/account/keys` | Bearer/session | Mint; secret once |
| POST | `/v1/account/keys/revoke` | Bearer/session | `{ keyHash }` |
| GET | `/v1/auth/challenge` | no | Solana SIWS challenge |
| POST | `/v1/auth/keys` | signed challenge | Mint from wallet |
| POST | `/v1/auth/passkey/*` | WebAuthn | Humans |
| GET | `/v1/deposits/solana` | Bearer/session | Deposit address |
| POST | `/v1/deposits/solana/sync` | Bearer/session | Auto-credit scan |
| POST | `/v1/deposits/solana/confirm` | Bearer/session | Credit by signature |
| GET | `/v1/deposits/base` | Bearer/session | Base deposit address |
| POST | `/v1/deposits/base/sync` | Bearer/session | Auto-credit scan |
| POST | `/v1/deposits/base/confirm` | Bearer/session | Credit by txHash |
| POST | `/v1/deposits/stripe/checkout` | Bearer/session | Card top-up |

Admin routes (`/v1/admin/*`) require `ADMIN_API_KEY`. They are operator-only.

## Quote example

```bash
curl https://api.bu0y.com/v1/quote \
  -H 'content-type: application/json' \
  -d '{"model":"glm4.6","inputTokens":1500,"maxOutputTokens":800}'
```

Response includes `best` (winning source, reserve micros, confidence) and `quotes[]` from every source that answered. Use the same `model` id on fill.

## Fill example

```bash
export BU0Y_KEY=bu0y_…
curl https://api.bu0y.com/v1/chat/completions \
  -H "Authorization: Bearer $BU0Y_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "model": "glm4.6",
    "messages": [{"role":"user","content":"hi"}],
    "max_tokens": 256
  }'
```

OpenAI SDK: set `baseURL` to `https://api.bu0y.com/v1` and `apiKey` to the `bu0y_…` secret.

Always send an output ceiling (`max_tokens` or `max_completion_tokens`). If omitted, the gateway imposes one so the reserve cannot run unbounded.

## Agent mint example

```bash
# 1) challenge
curl "https://api.bu0y.com/v1/auth/challenge?address=$PUBKEY"

# 2) sign message with wallet ed25519; POST
curl https://api.bu0y.com/v1/auth/keys \
  -H 'content-type: application/json' \
  -d '{"message":"…","signature":"…","label":"agent"}'

# 3) fund
curl -H "Authorization: Bearer $KEY" https://api.bu0y.com/v1/deposits/solana
# send USDC to depositAddress, then:
curl -X POST -H "Authorization: Bearer $KEY" \
  https://api.bu0y.com/v1/deposits/solana/sync
```

## Errors agents should expect

| Status | Meaning |
|--------|---------|
| 401 | Missing / bad Bearer or session |
| 400 | Bad body, below deposit minimum, no USDC in tx |
| 404 | Model unknown to every source |
| 409 | Idempotency-Key reuse |
| 429 | Rate limit |
| 503 | No offer clears the margin floor, or deposits not configured |

`SourceError` kinds that **do not** fail over: `auth`, `malformed_response` (upstream may already have billed). Transient / capacity errors may try another source.

## Privacy

Bu0y does not store your prompts or completions. We keep billing metadata only. The marketplace that fills the request still receives the prompt to run it. We do not claim anonymity or zero retention on that upstream.

- Public `/v1/stats` is aggregate only
- Key list returns hashes, never raw secrets after mint
- Usage records: request id, timestamps, account, model requested/served, source, token counts, reserved/billed/cogs/margin, latency, status

## Site map for agents

| URL | Purpose |
|-----|---------|
| https://bu0y.com/llms.txt | This index’s short form |
| https://bu0y.com/llms-full.txt | This file |
| https://bu0y.com/docs.html | Human docs |
| https://bu0y.com/docs.md | Markdown twin |
| https://bu0y.com/ | Marketing + live harbor sheet |
| https://bu0y.com/models.html | Searchable catalog; copy model ids for clients |
| https://bu0y.com/account.html | Passkey desk |

## Open questions / out of scope for customers

- No withdraw API
- Operator CCTP / profit sweep are ops rails, not customer endpoints
- Customers may deposit Base USDC for credits; they never approve Surplus SettlementV2