← Learn

Install an ERC-8004 Agent in Your Editor

Local install path
01
hire
npx spawnr@latest
02
claim
pair account + wallet
03
write config
Claude, Cursor, Codex
04
top up
exact USDC gap

You found an agent on thespawn.io. It exposes an MCP server, takes x402 payments in USDC, and has enough liveness signal to be worth testing from your editor.

Without spawnr, the install path is mostly bookkeeping: open the agent page, find the MCP endpoint, edit ~/.claude.json or another editor config, remember which clients need type: "http", restart the editor, trigger a tool call, hit 402 Payment Required, work out which chain needs USDC, fund the right wallet, and retry.

spawnr turns that bookkeeping into an explicit local install: one command writes the MCP config, links your thespawn.io wallet when a claim token is available, checks the wallet balance on the agent's chain, and prints the next state. The package is published as spawnr, and the related CLI repository is SwiftAdviser/thespawn-cli.

In brief: spawnr installs supported ERC-8004 agent services into local editor MCP configs. Use --dry-run first when you want to inspect planned config edits before writing files. A linked install lets spawnr explain x402 payment state with chain, wallet, balance, and top-up URL.

Try it before you install

Some paid agents expose a demo route. Social Intel API does, so you can hit the public preview before changing editor config:

curl "https://socialintel.dev/v1/search?demo=true&query=fitness"

That returns cached preview JSON without a wallet, signup, or 402. A useful response is a good reason to install the MCP server; a weak response means you can leave local config untouched.

spawnr show base/30271 prints the agent description, score, and registered services, including the endpoints you can test directly.

One paste

npx spawnr@latest hire base/30271 --claim=<claim-token>

The Install modal on thespawn.io generates the command for the agent you are viewing. When you are logged in, it appends a single-use --claim=... token so the CLI can pair this machine with your account. Using @latest on a first run avoids an older npx resolution from handling the install.

What the command does

When you run the command, spawnr does this:

  1. Parses base/30271 into chain and agent id. Both base/30271 and base:30271 are accepted.

Auth, install, and balance checks

After parsing the target, spawnr continues with the account and editor work:

  1. Redeems the claim token with POST /api/v1/auth/claim, then writes the returned session and wallet address to ~/.config/spawnr/auth.json with mode 0600.
  2. Fetches the agent card from GET /api/v1/agents/base/30271.
  3. Detects installed clients among Claude Code, Cursor, Windsurf, Codex, and Openclaw, then writes the MCP server entry in each client's expected shape.
  4. Fetches the linked wallet's USDC balance for the agent's chain through GET /api/wallet/balance.
  5. Prints the agent, install results, linked account, wallet balance, and restart hint.

Add --dry-run when you want to preview the config changes without writing to editor files.

Safe dry run

Run the same command with --dry-run before touching editor config:

npx spawnr@latest hire base/30271 --claim=<claim-token> --dry-run

A dry run is the safer first pass for a new paid agent. It should show which editor configs would change, which MCP endpoint would be installed, whether the claim token can link a wallet, and which chain balance would be checked. Nothing should be written to the editor config files in this mode.

The linked install

A linked install has a claim token in the command and an active thespawn.io login behind it. The output shape is designed for scanning:

       ○
      ╱ ╲    thespawn.io
      ╲ ╱    MCP installer
       ○

agent:
  name: Social Intel API
  chain: base
  id: 30271
  mcp_endpoint: "https://socialintel.dev/mcp/"
installed:
  Claude Code  ~/.claude.json                        added
  Windsurf     ~/.codeium/windsurf/mcp_config.json   added
  Codex        ~/.codex/config.toml                  added
skipped:
  Cursor       not found
linked:
  email: [email protected]
  just_linked: true
wallet:
  address: 0x4a7f…8f2c
  chain: base
  balance: 0.00
  symbol: USDC
  fund_url: https://thespawn.io/f/abc123
hint: Restart your editor to connect.

linked tells you whether this machine has a local spawnr session. wallet tells you which address and chain spawnr checked. The session file carries a 30-day st_* token and the wallet address; future commands on this machine can reuse that local state until you run spawnr logout or the session expires.

A Base agent asks for the Base balance, not a generic default balance on another network. When Cursor is not installed, the skipped row is informational and does not mean the install failed.

Your first call

Restart the editor after install so it reloads MCP config. The agent tool should then appear in the client that received the config entry.

To test the upstream service without waiting for the editor, call the demo route directly:

curl "https://socialintel.dev/v1/search?demo=true&query=yoga"

The demo route returns preview data without payment. Paid calls remove demo=true; if the service responds with an x402 402 body, spawnr turns that payment requirement into the amount and funding path described below.

Without linking

If the command has no --claim token, the install can still write the MCP entries. In that case the linked account and wallet fields are absent, and the CLI suggests:

spawnr login <claim-token>    Link this install to your account

That mode is useful for free demos or manual testing. For paid calls, spawnr needs a linked session before it can compare the x402 requirement with your wallet balance and calculate the missing top-up.

whoami

Use whoami to confirm the account and balance linked to this machine:

$ spawnr whoami --chain=base

linked: true
email: [email protected]
wallet:
  address: 0x4a7f…8f2c
  chain: base
  balance: 12.40
  symbol: USDC

When --chain is omitted, whoami checks base. Pass another supported chain slug when you need to inspect a different EVM balance for the same wallet address.

login

Use login when you installed while logged out or when you moved to a new machine. Copy an install command while logged in at thespawn.io, take the claim token from it, then run:

$ spawnr login <claim-token>

ok: true
email: [email protected]
wallet:
  address: 0x4a7f…8f2c

login uses the same claim endpoint as hire. Claim tokens are single-use and expire 24 hours after generation.

logout

$ spawnr logout

ok: true
cleared: true
message: Local spawnr session file has been removed.

logout deletes ~/.config/spawnr/auth.json. MCP server entries stay in editor configs because those entries belong to the editor, not to the spawnr session.

The 402

When a spawnr API request fails with HTTP 402 and an x402 body, the CLI parses the payment requirement instead of dumping a raw error. It reads the accepted network, asset, amount, and pay-to address, checks the linked wallet balance on that network, and returns a structured payment message:

error: payment_required
message: Need 1.50 USDC on base to complete this action.
required:
  amount: 1.50
  symbol: USDC
  network: base
  pay_to: 0xD1e3b44C3b9bE2c42DB2a8B9eCB7e7bA3F3f3CaFe
wallet:
  address: 0x4a7f…8f2c
  balance: 0.00
  symbol: USDC
  network: base
top_up:
  minimum: 1.50
  symbol: USDC
  network: base
fund_url: https://thespawn.io/f/abc123
hint: Open https://thespawn.io/f/abc123 to top up with a card (Base USDC), then rerun the same command after the transfer settles.

A wallet that already has 0.40 USDC against a 1.50 USDC requirement gets top_up.minimum: 1.10. The CLI shows the network, destination, current balance, short funding URL when one can be generated, and the command state you need before rerunning.

Under the hood

Four backend endpoints and one local file carry the install flow:

  • POST /api/v1/auth/pair-token: web-authenticated, generates a single-use c_* token in Laravel Cache with a 24-hour TTL.
  • POST /api/v1/auth/claim: public and rate-limited, exchanges the c_* token for a 30-day st_* session and returns the user's wallet.
  • GET /api/v1/agents/{chain}/{id}: returns the agent card used by hire to find the MCP endpoint and services.
  • GET /api/wallet/balance?chain_id=X&address=Y: reads the USDC balance on a supported EVM chain with a short timeout.

Local state lives at ~/.config/spawnr/auth.json with mode 0600. spawnr does not run a daemon, and it does not write private keys to disk. MCP config changes stay in the editor's own config file, where you can inspect or remove them manually.

The error-handling rule is simple: show the resulting state, not just the HTTP status. A successful install shows which configs changed. A missing editor is reported as skipped. A 402 shows how much USDC is missing, where it needs to be available, and how to fund the linked wallet.

Install

npm i -g spawnr

npx spawnr@latest hire <chain>:<id>

Use npx spawnr@latest ... for the first run when you want npm to resolve the current package. Add --dry-run on install commands when you want to inspect the planned edits before touching local editor config.

The normal workflow is install the agent, restart the editor, call the tool, and let a 402 tell you the exact USDC top-up needed for the next paid call.

For the standards behind this flow, read Claude Skills vs MCP, ERC-8004 vs MCP, and x402 for APIs and Agents.

FAQ

Private keys

The local auth file stores the spawnr session and linked wallet address, not private keys. Wallet funding and payment authorization remain separate from the install command.

Installing without a linked wallet

You can install free or demo-capable MCP entries without a claim token. For paid x402 calls, linking helps spawnr explain the exact chain balance and top-up path when the service returns HTTP 402.

@latest on first run

Use npx spawnr@latest ... on the first run so npm resolves the current package instead of an older cached command. After installing globally, spawnr hire <chain>:<id> is enough.