antseed-connect

# AntSeed — Integration Skill

> This file is the agent-readable companion to https://antseed.com/integrations.
> It tells any AI agent (Claude, Codex, OpenClaw, Hermes, custom) exactly
> how to wire its tool of choice up to the AntSeed peer-to-peer inference network.

## What is AntSeed?

AntSeed is a peer-to-peer marketplace for AI inference. Buyers run a small
local daemon (the **buyer proxy**) that exposes an HTTP API at
`http://localhost:8377` speaking the three caller-facing LLM API protocols:
Anthropic Messages, OpenAI Chat Completions, and OpenAI Responses. Legacy
OpenAI Completions is supported internally for adapter translation. The proxy
discovers providers on a DHT, routes the
request to a peer, translates between protocols when needed (via
`@antseed/api-adapter`), and settles in USDC on Base.

Important: AntSeed is for value-added AI services (specialized models, agents,
TEEs, fine-tunes, managed workflows), not raw resale of API keys or subscription
access. Providers must comply with upstream terms of service.

From the perspective of any tool, SDK, or agent, **AntSeed is just a local
OpenAI/Anthropic-compatible endpoint** — point a `base_url` at it and you are done.

## Glossary (mental model)

- **Buyer proxy** — the local server on `localhost:8377` that accepts API calls
  from your tools and forwards them to AntSeed peers. It is the only thing your
  editor / agent / SDK ever talks to.
- **Peer** — someone selling inference. Each peer has a `peerId` (40-char hex),
  a display name, and a list of services. List with `antseed network browse`.
- **Service** — a single model id like `claude-sonnet-4-6` or `deepseek-v4-flash`.
  *This is what you pass as `model` in your tool's config.* Each service has its
  own native protocol list and its own `in` / `cachedIn` / `out` pricing.
- **Protocols** (per service) — the wire formats a service accepts *natively*,
  advertised on each peer in `providerServiceApiProtocols[provider].services[service]`.
  Values are `anthropic-messages`,
  `openai-chat-completions`, `openai-responses`, `openai-completions`. **This is
  the field to match your tool's wire format against.** If your tool's wire format
  is in this list, the request passes through untouched; if not, the api-adapter
  translates on the fly.
- **Cached input pricing** — services charge a separate, much lower rate
  (typically 4–10×) for tokens that are reused across requests: system prompts,
  tool schemas, prior conversation turns, long files you keep referencing. The CLI
  exposes it as `cachedInputUsdPerMillion`. For long-running agents and chatbots,
  this is often the dominant cost line.
- **Pin** — telling the buyer proxy "route requests to *this* peer." In the
  default manual flow, there is no peer auto-selection; you must choose a peer,
  send a per-request pin header, or start the proxy with a router plugin that
  performs selection. Common explicit routes:
  - **Session pin**: `antseed buyer connection set --peer <peerId>`. Persists in
    `~/.antseed/buyer.state.json` and applies to every request until you change it.
  - **Per-request header**: `x-antseed-pin-peer: <peerId>` on each call. Overrides
    the session pin for that request, and works *without* any session pin at all.
  - **Model prefix**: set `model` to `<peerId>@<service>`. The proxy uses the
    prefix as the peer pin and forwards only `<service>` to the seller.
  
  If both header and model-prefix pins are present, the header selects the peer;
  the model prefix is still stripped before routing.
  Until at least one of these is in effect, every request returns `no_peer_pinned`.

## Universal setup (do this once)

### Option A — VPR desktop app (easiest)

Download from https://antseed.com — it ships the buyer proxy, a wallet, and a
peer browser in a GUI. While the app is open the proxy is reachable at
`http://localhost:8377`.

### Option B — CLI (headless / servers / agents)

```bash
# 1. Install
npm install -g @antseed/cli

# 2. Identity (an EVM private key — 64 hex chars). Save this somewhere safe;
#    you will reuse it across machines and it controls your USDC deposits.
export ANTSEED_IDENTITY_HEX=$(openssl rand -hex 32)
# SECURITY: never paste this key into chat, logs, GitHub issues, or a file
# committed to git. It controls the buyer identity and access to deposits.

# 3. Start the buyer proxy on :8377
antseed buyer start &

# 4. Browse the network and list every service (= model) each peer offers,
#    along with its native protocols and USD-per-1M-tokens pricing.
#    `service` is the model id you pass to your tool. `protocols` is the
#    wire format(s) the service accepts natively — match it against your
#    tool. `in` / `cachedIn` / `out` are fresh-input / cached-input / output.
antseed network browse --json --top 5 \
  | jq '.peers | map({
      peerId, name: .displayName,
      services: [
        (.providerServiceApiProtocols | to_entries[]) as $p
        | ($p.value.services | to_entries[]) as $s
        | {
            service:  $s.key,
            protocols: $s.value,
            in:       (.providerPricing[$p.key].services[$s.key].inputUsdPerMillion       // .providerPricing[$p.key].defaults.inputUsdPerMillion),
            cachedIn: (.providerPricing[$p.key].services[$s.key].cachedInputUsdPerMillion // null),
            out:      (.providerPricing[$p.key].services[$s.key].outputUsdPerMillion      // .providerPricing[$p.key].defaults.outputUsdPerMillion)
          }
      ]
    })'

# 5. Inspect one peer in detail. Use `matchingServices[]` for pricing/tags and
#    `peer.providerServiceApiProtocols` for native protocol support.
#    `cachedIn` is typically 4–10× cheaper than `in` and often dominates the
#    cost line for long-running agents and chatbots — always include it when
#    comparing peers.
antseed network peer <peerId> --json \
  | jq '{
      peer: (.peer | { peerId, name: .displayName,
                       sessions: .onChainChannelCount,
                       gho