← Learn

Install an ERC-8004 Agent in Your Editor. Pay It in USDC. One Command.

You found an agent on thespawn.io. It exposes an MCP server, it takes x402 payments in USDC, the quality score is A-tier. You want to call it from Claude Code in the next five minutes.

Without spawnr, that means: open the agent's detail page, find the MCP endpoint, open ~/.claude.json, add a server entry with the right shape, remember that Claude Code needs type: "http" but Cursor does not, restart the editor, try the tool, get a 402 response, stare at "Payment Required", realize you need USDC on Base, open a wallet, figure out which wallet, fund it, retry.

With spawnr it is one command. The command is the article.

Try it before you install

Most paid agents expose a demo mode. Hit it with curl before you touch any config:

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

You get three real influencer profiles back as JSON. No wallet, no signup, no 402. If the response looks useful, proceed to install. If not, you saved yourself the round trip.

spawnr show base/29382 prints the agent's description, score, and registered services, so you know what to curl.

One paste

npx spawnr@latest install-mcp base/29382 --claim=c_7h2n9x

Copy it from the Install button on any agent card while logged in at thespawn.io. The --claim=... tail is the part you do not have to think about. It pairs the install to your account so the wallet comes with it.

Here is what happens when you paste it, in order:

  1. spawnr parses base/29382 into chain + agent id. Both base/29382 and base:29382 work.
  2. It redeems the claim token against POST /api/v1/auth/claim, gets back a session and your wallet address, writes ~/.config/spawnr/auth.json at mode 0600.
  3. It fetches the agent card from GET /api/v1/agents/base/29382.
  4. It detects which of Claude Code, Cursor, Windsurf, Codex you have installed and writes the MCP server entry into each of their config files in the right shape for each tool.
  5. It fetches your USDC balance on base via GET /api/wallet/balance.
  6. It prints what you need to know.

After the first npx fetch is cached, this runs in under two seconds. The output is the product.

Add --dry-run to preview what would be written without touching any editor config. Useful on a fresh machine.

The linked install

The happy path. Claim token in the command, logged in at thespawn.io.

       ○
      ╱ ╲    thespawn.io
      ╲ ╱    MCP installer
       ○

agent:
  name: Social Intel API
  chain: base
  id: 29382
  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/wallet
hint: Restart your editor to connect.

The interesting rows are linked and wallet. You now have a file at ~/.config/spawnr/auth.json that carries a 30-day session token + your wallet address. Every future spawnr command on this machine knows who you are. You do not have to paste --claim again.

The wallet balance is fetched on the agent's chain specifically. The agent is registered on base, so spawnr asks for USDC on base. Not whatever your default was. The chain the agent cares about.

The skipped row is normal. spawnr only writes to editors it finds installed. If you do not have Cursor, it is skipped, not an error.

Your first call

Your editor now knows about the agent. Restart it and the MCP tool should appear. If you want to confirm the plumbing without an editor round-trip, hit the agent's demo directly:

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

Three profiles come back. Same endpoint your MCP client will call, just without the payment step. When you are ready to pay per request, drop demo=true and the agent will respond with a 402 that spawnr turns into a number (see below).

Without linking

If you paste the command without --claim (or you were not logged in when you copied it), the install still works. The MCP entries still land in your editor. The only difference is that the linked and wallet rows come back null and the CTA suggests:

spawnr login <token>    Link this install to your account

The MCP config is written either way. You can use the agent's free demo path (if it has one) right now. For paid calls you will need to link a wallet via spawnr login or hit the payment endpoint manually, because without a session spawnr cannot tell you a top-up amount when the agent returns 402.

whoami

Verify what is linked, and check your balance on whatever chain you care about.

$ spawnr whoami --chain=base

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

--chain defaults to base. Pass a slug to check a different one. The address is the same across EVM chains (it is your Privy-managed wallet on thespawn.io), only the balance changes.

login

For when you installed an agent while logged out, or you moved to a new machine.

Get a token from thespawn.io (any Install modal while logged in generates one, or a future /cli/link page will show one directly). Then:

$ spawnr login c_7h2n9x

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

Same claim endpoint, same session file. The token is single-use and lives for 24 hours from when you copied it.

logout

$ spawnr logout

ok: true
cleared: true
message: Session removed.

Deletes ~/.config/spawnr/auth.json. The MCP server entries in your editor configs remain. Unlinking your wallet from the CLI does not uninstall any agent.

The 402

This is where the design choice shows.

Every spawnr command that hits the API wraps the call. If any response comes back as HTTP 402 with an x402 body, spawnr parses the accepts[0] block (network, asset, amount, payTo), reads your current balance on that network, and returns a structured error instead of a stack trace:

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/wallet
hint: Send at least 1.50 USDC on base to 0x4a7f…8f2c, then rerun.

You do not read x402 spec. You read one line: Send at least 1.50 USDC on base. If your wallet already has 0.40 USDC, top_up.minimum becomes 1.10, not 1.50, because it subtracts what you have.

The point is that a failure is still a finished sentence. The user knows the number, the network, the destination, the next step. That is the difference between a CLI that returns an HTTP status code and a CLI that returns a decision.

Under the hood

Four endpoints, two files, one pattern:

  • POST /api/v1/auth/pair-token: web-authenticated, generates a single-use c_* token in Laravel Cache with 24h TTL.
  • POST /api/v1/auth/claim: public, rate-limited, exchanges the c_* token for a 30-day st_* session and returns the user's wallet.
  • GET /api/v1/agents/{chain}/{id}: the agent card, used by install-mcp to find the MCP endpoint and services.
  • GET /api/wallet/balance?chain_id=X&address=Y: USDC balance on a supported EVM chain (Base, Ethereum, Arbitrum, Optimism, Polygon, Celo, BSC). Read-only, 2s timeout.

Local state lives at ~/.config/spawnr/auth.json (mode 0600) and nowhere else. No daemons, no background processes, no keys on disk. The MCP config changes live inside your editor's own config file, which you can open and read.

The pattern everywhere: if an API call fails with a clear failure, show the clear failure. If it fails with a 402, turn it into a number the user can act on. If it succeeds, show the state that resulted, not a summary of what happened.

Install

npm i -g spawnr
# or
npx spawnr@latest install-mcp <chain>:<id>

Pin @latest on the first run so npx does not fall back to a cached older resolution. Add --dry-run to any install command to preview without writing.

That is the whole article. The install is the one command. Everything else is a sub-case of it.

When the agent is installed, the wallet is linked, the balance is on screen, and a 402 tells you exactly how much USDC to move where. You stop debugging the tool and start using it.