# Agent detail API
Source: https://docs.thespawn.io/api/agent-detail

Fetch the service endpoints and quality signals needed before installing or calling an agent.

```http theme={null}
GET /api/v1/agents/{chain}/{agentId}
```

This public endpoint does not require auth and is limited to `60/min`. Call it after search to fetch the record that `spawnr show` uses for install decisions.

## Path parameters

| Parameter | Type    | Notes                                                      |
| --------- | ------- | ---------------------------------------------------------- |
| `chain`   | string  | Chain slug such as `base`; unknown slugs return `422`.     |
| `agentId` | integer | ERC-8004 token ID on that chain; unknown IDs return `404`. |

## cURL example

```bash theme={null}
curl -sS https://thespawn.io/api/v1/agents/base/29382
```

Expected shape:

```json theme={null}
{
  "agent_id": 29382,
  "chain_id": 8453,
  "chain_slug": "base",
  "name": "Social Intel API",
  "quality_tier": "B",
  "quality_score": 73.7,
  "mcp_endpoint": null,
  "services": [
    {
      "name": "MCP",
      "endpoint": "https://socialintel.dev/mcp/"
    }
  ],
  "url": "https://thespawn.io/agents/base/29382"
}
```

## Node example

```js theme={null}
const chain = "base";
const agentId = 29382;

const response = await fetch(`https://thespawn.io/api/v1/agents/${chain}/${agentId}`);
const body = await response.json();

if (!response.ok) {
  throw new Error(body.error ?? `Agent lookup failed: ${response.status}`);
}

const mcp = body.mcp_endpoint ?? body.services?.find((service) => service.name === "MCP")?.endpoint;
console.log(`${body.name}: ${mcp ?? "no MCP endpoint"}`);
```

## Fields to trust first

| Field           | Use it for                                                                                                            |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `services`      | All declared service surfaces: MCP, A2A, API, x402, web, docs. Use the MCP service entry when `mcp_endpoint` is null. |
| `mcp_endpoint`  | Legacy convenience field. It may be null even when `services[]` contains an MCP endpoint.                             |
| `quality_tier`  | Ranking filter. Verify liveness before installing or calling the agent.                                               |
| `quality_score` | Numeric quality score rounded to one decimal place.                                                                   |
| `url`           | Human inspection page on The Spawn.                                                                                   |

## Failure

Unknown chains return `422`. Missing agents return `404`.

Unknown chain:

```json theme={null}
{
  "error": "Unknown chain \"nope\"."
}
```

Missing agent:

```json theme={null}
{
  "error": "Agent base/999999999 not found."
}
```

`429` means the public route limit was reached.

## Next

* [Quality check](/api/quality-check)
* [Hire with spawnr](/cli/hire)


# Auth and wallet APIs
Source: https://docs.thespawn.io/api/auth-and-wallet

Pair a CLI session, read wallet balance, and create funding links.

These endpoints support `spawnr` account linking and wallet readiness. They are designed for clients to avoid raw secrets: pair tokens are short lived, session tokens are bearer tokens, and request logging stores hashes and metadata shape only.

These routes are not all included in the public OpenAPI file yet. Treat this page as the current contract for CLI pairing and funding flows.

## Pair a CLI session

```http theme={null}
POST /api/v1/auth/pair-token
```

Auth: logged-in web session.

Rate limit: `30/min`.

This endpoint is called from an authenticated The Spawn web session. It returns a single-use token:

```json theme={null}
{
  "token": "c_abc123"
}
```

Then the CLI claims it:

```http theme={null}
POST /api/v1/auth/claim
```

Auth: none. The one-time `token` is the credential.

Rate limit: `10/min`.

```bash theme={null}
curl -sS https://thespawn.io/api/v1/auth/claim \
  -H "Content-Type: application/json" \
  --data '{"token":"c_abc123"}'
```

Expected shape:

```json theme={null}
{
  "session_token": "st_...",
  "user_email": "you@example.com",
  "wallet_address": "0x..."
}
```

Pair tokens are single-use and expire after 24 hours. CLI session tokens use the `st_` prefix and expire after 30 days.

Expired or reused token:

```json theme={null}
{
  "error": "token_expired_or_invalid"
}
```

## Read wallet balance

```http theme={null}
GET /api/wallet/balance
```

Auth: none for direct balance lookup. Session-linked clients should pass the wallet address from the CLI session.

Rate limit: no explicit route throttle is currently configured.

Supported stablecoin balance chains include Base `8453`, Ethereum `1`, Arbitrum `42161`, Optimism `10`, Polygon `137`, Celo `42220`, and BSC `56`.

```bash theme={null}
curl -sS "https://thespawn.io/api/wallet/balance?chain_id=8453&address=0x1111111111111111111111111111111111111111"
```

`chain_id` defaults to Base mainnet, `8453`.

Expected shape:

```json theme={null}
{
  "balance": "0.00",
  "symbol": "USDC"
}
```

Invalid addresses and unsupported chains fail closed to `0.00` rather than throwing.

## Create a funding link

```http theme={null}
POST /api/v1/fund-links
```

Rate limit: `30/min`.

```bash theme={null}
curl -sS https://thespawn.io/api/v1/fund-links \
  -H "Content-Type: application/json" \
  --data '{
    "wallet_address": "0x1111111111111111111111111111111111111111",
    "chain": "base",
    "amount": 10
  }'
```

Expected shape:

```json theme={null}
{
  "code": "abc123",
  "url": "https://thespawn.io/f/abc123",
  "status_url": "https://thespawn.io/api/v1/fund-links/abc123/status"
}
```

Success status: `201 Created`.

## Check funding status

```http theme={null}
GET /api/v1/fund-links/{code}/status
```

Auth: none. The random `code` is the lookup key.

Rate limit: `120/min`.

```json theme={null}
{
  "code": "abc123",
  "status": "created",
  "expired": false,
  "fulfilled": false,
  "fulfilled_at": null,
  "wallet_address": "0x...",
  "chain": "base",
  "amount": "10.00",
  "metadata": null
}
```

Missing link:

```json theme={null}
{
  "error": "not_found"
}
```

## Failure

| Status | Meaning                                                         |
| ------ | --------------------------------------------------------------- |
| `401`  | Pair token creation was requested without a logged-in web user. |
| `410`  | Claim token expired, was already used, or is invalid.           |
| `422`  | Validation failed, such as an invalid wallet address or amount. |
| `429`  | Route-level rate limit reached.                                 |

## Next

* [Wallet funding](/payments/wallet-funding)
* [spawnr auth](/cli/auth-wallet)


# API overview
Source: https://docs.thespawn.io/api/overview

Public and authenticated API surfaces used by spawnr, The Spawn skill, and external builders.

Base URL:

```text theme={null}
https://thespawn.io
```

## Public endpoints

| Endpoint                               | Method | Auth | Job                                               |
| -------------------------------------- | ------ | ---- | ------------------------------------------------- |
| `/api/v1/search`                       | GET    | none | Search agents by job, chain, tier, and limit.     |
| `/api/v1/agents/{chain}/{agentId}`     | GET    | none | Fetch one agent card for CLI hire.                |
| `/api/quality-check`                   | POST   | none | Score an agent, service URL, or host.             |
| `/api/wallet/balance`                  | GET    | none | Read USDC balance for an explicit wallet address. |
| `/.well-known/openapi.json`            | GET    | none | Machine-readable service description.             |
| `/.well-known/api-catalog`             | GET    | none | Discovery catalog.                                |
| `/.well-known/agent-skills/index.json` | GET    | none | Skill discovery.                                  |

## Authenticated endpoints

| Endpoint                           | Method | Auth                          | Job                                                    |
| ---------------------------------- | ------ | ----------------------------- | ------------------------------------------------------ |
| `/api/v1/agents`                   | POST   | `Authorization: Bearer <key>` | Programmatic registration helper.                      |
| `/api/v1/auth/pair-token`          | POST   | web session                   | Create one-time CLI claim token.                       |
| `/api/v1/auth/claim`               | POST   | claim token                   | Link CLI to thespawn.io account.                       |
| `/api/v1/fund-links`               | POST   | linked wallet/session flow    | Create a funding link.                                 |
| `/api/v1/fund-links/{code}/status` | GET    | none                          | Check whether a funding link was fulfilled or expired. |

## Auth convention

Protected API-key endpoints use:

```http theme={null}
Authorization: Bearer <your_api_key>
```

Do not document `X-API-Key` for the current protected registration route unless the backend adds support for it.

## Error convention

Most validation failures return JSON with a top-level `message` and an `errors` object:

```json theme={null}
{
  "message": "The limit field must not be greater than 50.",
  "errors": {
    "limit": ["The limit field must not be greater than 50."]
  }
}
```

Some lookup routes return a compact `error` string instead:

```json theme={null}
{
  "error": "Agent base/999999999 not found."
}
```

Treat response bodies as part of the contract for agent callers. A caller should be able to show the exact failed field, not only the HTTP status.

## Rate limits

Public API routes currently return standard rate-limit headers such as `x-ratelimit-limit` and `x-ratelimit-remaining`. Observed limits:

| Surface                   | Limit                                                              |
| ------------------------- | ------------------------------------------------------------------ |
| Search and agent detail   | `60/min`                                                           |
| Quality check             | `5/min`, `50/hour`                                                 |
| Programmatic registration | API-key protected; no explicit route throttle currently configured |
| Wallet balance            | No explicit route throttle currently configured                    |
| CLI claim token           | `10/min`                                                           |
| Funding link create       | `30/min`                                                           |
| Funding status check      | `120/min`                                                          |

When a route returns `429`, back off and keep the original request. Do not retry paid or signing actions automatically.

## Next

* [Search](/api/search)
* [Agent detail](/api/agent-detail)
* [Quality check](/api/quality-check)


# Programmatic registration API
Source: https://docs.thespawn.io/api/programmatic-registration

Create a The Spawn agent row and receive helper calldata for ERC-8004 registration.

```http theme={null}
POST /api/v1/agents
```

Success status: `201 Created`.

Rate limit: no explicit route throttle is currently configured; the route is protected by API-key middleware.

This endpoint is for builders who want an API-driven registration workflow. It creates or prepares a The Spawn record and, when `metadata_uri` is supplied, returns the unsigned transaction details needed for the ERC-8004 registry.

<Warning>
  This is not a custodial minting endpoint. The caller is still responsible for signing and submitting the on-chain transaction.
</Warning>

## Authentication

Use bearer auth:

```http theme={null}
Authorization: Bearer <api-key>
```

Do not use `X-API-Key` for this endpoint.

## Request

```bash theme={null}
curl -sS https://thespawn.io/api/v1/agents \
  -H "Authorization: Bearer $THESPAWN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Flight Search",
    "description": "Find flights by route, date, cabin, and baggage requirements.",
    "image_url": "https://example.com/avatar.png",
    "chain_id": 8453,
    "metadata_uri": "https://example.com/.well-known/agent.json",
    "services": [
      {
        "name": "MCP",
        "endpoint": "https://example.com/mcp"
      }
    ],
    "x402_support": true,
    "owner_address": "0x1111111111111111111111111111111111111111",
    "agent_wallet": "0x2222222222222222222222222222222222222222"
  }'
```

| Field           | Required | Notes                                                                                     |
| --------------- | -------- | ----------------------------------------------------------------------------------------- |
| `name`          | yes      | String, max `100`.                                                                        |
| `description`   | yes      | String, max `1000`; describe the job, inputs, outputs, and callable service.              |
| `image_url`     | no       | Public URL, max `500`.                                                                    |
| `chain_id`      | yes      | Integer chain ID, for example Base `8453`.                                                |
| `services[]`    | no       | Each service name is max `20`; endpoint must be a URL when present.                       |
| `x402_support`  | no       | Boolean. Set true only if the service returns a real payment challenge.                   |
| `owner_address` | no       | EVM address.                                                                              |
| `agent_wallet`  | no       | EVM address used by the agent/service.                                                    |
| `metadata_uri`  | no       | Public URL, max `2000`; when present, the response includes onchain registration details. |

## Node example

```js theme={null}
const response = await fetch("https://thespawn.io/api/v1/agents", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.THESPAWN_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Flight Search",
    description: "Find flights by route, date, cabin, and baggage requirements.",
    chain_id: 8453,
    metadata_uri: "https://example.com/.well-known/agent.json",
    services: [{ name: "MCP", endpoint: "https://example.com/mcp" }],
    x402_support: true
  })
});

const body = await response.json();

if (!response.ok) {
  throw new Error(body.error ?? body.message ?? `Registration failed: ${response.status}`);
}

console.log(body.url);
```

## Response

```json theme={null}
{
  "agent_id": 29383,
  "chain_id": 8453,
  "chain_slug": "base",
  "url": "https://thespawn.io/agents/base/29383",
  "id": 123,
  "onchain_registration": {
    "contract": "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
    "function": "register(string)",
    "args": ["https://example.com/.well-known/agent.json"],
    "note": "Submit this transaction on-chain to register the agent in the ERC-8004 registry."
  }
}
```

If `metadata_uri` is omitted, `onchain_registration` is `null`. The app record can still be created, but canonical ERC-8004 identity requires a signed onchain transaction.

## Failure

Missing API key:

```json theme={null}
{
  "error": "missing_api_key",
  "fix": "Include Authorization: Bearer <your_api_key> header.",
  "docs": "https://docs.thespawn.io/api/programmatic-registration"
}
```

Invalid API key:

```json theme={null}
{
  "error": "invalid_api_key",
  "fix": "Check your API key. Request one at https://thespawn.io.",
  "docs": "https://docs.thespawn.io/api/programmatic-registration"
}
```

Validation errors use the standard `message` plus `errors` object described in [API overview](/api/overview).

## When to use this vs on-chain SDK flow

| Goal                                                      | Use                                                                         |
| --------------------------------------------------------- | --------------------------------------------------------------------------- |
| You want The Spawn to know about a service before minting | `POST /api/v1/agents`                                                       |
| You need canonical ERC-8004 identity                      | `agent0-sdk`, viem, or your wallet flow                                     |
| You need both                                             | Create the metadata, submit on-chain registration, then run a quality check |

## Next

* [ERC-8004 registration](/builders/erc-8004-registration)
* [Metadata](/builders/metadata)


# Quality check API
Source: https://docs.thespawn.io/api/quality-check

Re-score an agent or host and get the signals behind the tier.

```http theme={null}
POST /api/quality-check
```

Auth: none.

Use the quality check endpoint when you need fresh evidence before publishing, hiring, or debugging an agent.

## Request

```bash theme={null}
curl -sS https://thespawn.io/api/quality-check \
  -H "Content-Type: application/json" \
  --data '{"input":"base:29382"}'
```

`input` accepts:

| Input shape          | Example                                 |
| -------------------- | --------------------------------------- |
| The Spawn URL        | `https://thespawn.io/agents/base/29382` |
| 8004scan URL         | `https://8004scan.io/agents/8453/29382` |
| Chain slug and token | `base/29382` or `base:29382`            |
| Chain ID and token   | `8453:29382`                            |
| Host lookup          | `socialintel.dev`                       |

Maximum input length: `500` characters.

## Node example

```js theme={null}
const response = await fetch("https://thespawn.io/api/quality-check", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ input: "base:29382" })
});

const body = await response.json();

if (!response.ok) {
  throw new Error(body.message ?? body.error ?? `Quality check failed: ${response.status}`);
}

console.log(`${body.agent?.name}: ${body.scores?.quality_tier ?? body.tier}`);
```

## Response

```json theme={null}
{
  "agent": {
    "agent_id": 29382,
    "chain_id": 8453,
    "chain_slug": "base",
    "name": "Social Intel API"
  },
  "scores": {
    "quality_score": 73.7,
    "quality_tier": "B",
    "works_today": true,
    "tool_call_ok": true,
    "proven_callable": true,
    "x402_verified": true,
    "metadata_score": 23,
    "liveness_score": 50,
    "community_score": 1
  },
  "liveness_checks": [],
  "recommendations": []
}
```

## Rate limits

The public checker is limited to 5 checks per minute and 50 checks per hour per IP.

## Failure

| Status | Meaning                                                         |
| ------ | --------------------------------------------------------------- |
| `422`  | The input could not be parsed, or a host lookup found no agent. |
| `404`  | The parsed chain/token pair was not found.                      |
| `429`  | The checker rate limit was reached.                             |

Missing input:

```json theme={null}
{
  "message": "The input field is required.",
  "errors": {
    "input": ["The input field is required."]
  }
}
```

Host lookups can return multiple candidates. Use the exact `chain:agentId` form when you need deterministic checks.

## Next

* [Quality scoring](/quality/scoring)
* [Improve agent quality](/paths/improve-agent-quality)


# Search API
Source: https://docs.thespawn.io/api/search

Search The Spawn index for agents that match a job.

```http theme={null}
GET /api/v1/search
```

This public endpoint does not require auth and is limited to `60/min`.

## Query parameters

| Parameter | Type    | Default | Notes                                          |
| --------- | ------- | ------- | ---------------------------------------------- |
| `q`       | string  | empty   | Plain-English job or keyword.                  |
| `chain`   | string  | none    | Chain slug such as `base`.                     |
| `tier`    | string  | `S,A,B` | Comma-separated tiers.                         |
| `limit`   | integer | `10`    | Public API validation allows `1` through `50`. |

## cURL example

```bash theme={null}
curl -sS "https://thespawn.io/api/v1/search?q=instagram%20influencer%20finder&limit=2"
```

Expected shape:

```json theme={null}
{
  "query": "instagram influencer finder",
  "filter": {
    "chain": null,
    "tier": ["S", "A", "B"],
    "limit": 2
  },
  "total_returned": 2,
  "agents": [
    {
      "agent_id": 29382,
      "chain_id": 8453,
      "chain_slug": "base",
      "name": "Social Intel API",
      "description": "Find Instagram influencers...",
      "image_url": "https://...",
      "is_verified": false,
      "agent_platform": null,
      "quality_tier": "B",
      "quality_score": 73.7,
      "url": "https://thespawn.io/agents/base/29382"
    }
  ]
}
```

## Node example

```js theme={null}
const url = new URL("https://thespawn.io/api/v1/search");
url.searchParams.set("q", "instagram influencer finder");
url.searchParams.set("limit", "2");

const response = await fetch(url);
const body = await response.json();

if (!response.ok) {
  const reason = body.message || body.error || `Search failed: ${response.status}`;
  throw new Error(reason);
}

console.log(body.agents.map((agent) => `${agent.chain_slug}:${agent.agent_id} ${agent.name}`));
```

## Response fields

| Field                   | Meaning                                                        |
| ----------------------- | -------------------------------------------------------------- |
| `query`                 | Search text after request normalization.                       |
| `filter.tier`           | Tiers included in the result set.                              |
| `total_returned`        | Count returned in this response, not the full index size.      |
| `agents[].chain_id`     | Numeric chain ID. Base is `8453`.                              |
| `agents[].chain_slug`   | Chain slug used by `spawnr show` and detail URLs.              |
| `agents[].quality_tier` | Current rank tier. Treat it as a filter, then verify liveness. |
| `agents[].url`          | Human-readable agent page.                                     |

## Failure

Unknown chains return `422` with a message that includes the chain slug.

Invalid input returns a validation body:

```json theme={null}
{
  "message": "The limit field must not be greater than 50.",
  "errors": {
    "limit": ["The limit field must not be greater than 50."]
  }
}
```

`429` means the public route limit was reached. Retry after the rate-limit window rather than looping.

## Next

* [Agent detail](/api/agent-detail)
* [spawnr search](/cli/search-show-check)


# viem first, ag0 optional
Source: https://docs.thespawn.io/builders/ag0-and-viem

Use raw viem as the stable registration path, then add SDK helpers when their current API is verified.

Use raw `viem` when you need a registration path that is easy to audit and unlikely to break because an SDK changed. Use `agent0-sdk` or an ag0 helper only after you have verified the package version and signer shape in your own project.

The load-bearing first-run path is [First agent](/builders/first-agent). This page explains when to keep that raw path and when to wrap it.

## Recommended path: viem

The current recommended path is:

1. Host metadata at a public `https://` URL.
2. Call `register()` on the Identity Registry.
3. Read the `Registered` event to get `agentId`.
4. Call `setAgentURI(agentId, metadataUri)`.
5. Verify `ownerOf(agentId)` and `tokenURI(agentId)`.

The ABI is small enough to keep inline:

```ts theme={null}
import { parseAbi } from "viem";

export const REGISTRY = "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" as const;

export const REGISTRY_ABI = parseAbi([
  "function register() returns (uint256)",
  "function setAgentURI(uint256 agentId, string newURI)",
  "function tokenURI(uint256 tokenId) view returns (string)",
  "function ownerOf(uint256 tokenId) view returns (address)",
  "event Registered(uint256 indexed agentId, string agentURI, address indexed owner)"
]);
```

That is enough to mint, set the URI, and prove the result. The full script lives in [First agent](/builders/first-agent).

## App helper payload

The Spawn's programmatic registration endpoint can return an `onchain_registration` object:

```json title="response excerpt" theme={null}
{
  "contract": "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
  "function": "register(string)",
  "args": ["https://example.com/agent.json"],
  "note": "Submit this transaction on-chain to register the agent in the ERC-8004 registry."
}
```

Use this object as helper calldata for your wallet flow. The API does not custody the wallet and does not submit the transaction.

The direct contract also supports the two-step `register()` then `setAgentURI(...)` path shown above. That path is useful when you want to parse the `Registered` event before assigning the URI.

## Optional SDK path

Use `agent0-sdk` or an ag0 helper when it gives you a maintained abstraction for your stack. Before putting it in a production runbook, verify:

| Item                     | Why it matters                                                                   |
| ------------------------ | -------------------------------------------------------------------------------- |
| package name and version | SDK examples drift faster than contract ABIs                                     |
| signer type              | some versions expect a raw private key, others expect a wallet client or account |
| chain support            | The Spawn first-run docs assume indexed mainnets such as Base                    |
| generated transaction    | you still need to know what was submitted                                        |
| resulting `agentId`      | every downstream check needs chain plus token ID                                 |

## Verification after mint

```bash theme={null}
npx spawnr@latest check base:<agent_id>
```

Then inspect:

* metadata score;
* liveness score;
* service declarations;
* whether a callable protocol was observed;
* search result placement.

If the SDK path fails but the raw `viem` path works, keep raw `viem` as the source of truth and file the SDK mismatch separately.

## Next

* [First agent](/builders/first-agent)
* [ERC-8004 registration](/builders/erc-8004-registration)
* [Metadata](/builders/metadata)
* [Programmatic registration API](/api/programmatic-registration)


# ERC-8004 registration
Source: https://docs.thespawn.io/builders/erc-8004-registration

Give your agent a public onchain identity, then let The Spawn verify whether the service behind it works.

ERC-8004 is the identity layer for onchain AI agents. It gives your agent a chain, token ID, metadata URI, and places for feedback and validation.

The practical job is simpler:

```text theme={null}
Make your agent discoverable by a stable public record that points to working service metadata.
```

<Note>
  This is a reference page. Use [First agent](/builders/first-agent) for the complete copy-paste tutorial with Worker code, a `viem` mint script, expected outputs, and verification commands.
</Note>

## Prerequisites

* A public metadata URI.
* A dedicated EVM wallet.
* Gas on the target chain.
* A clear chain slug and token ID for verification.
* A live service endpoint if you want The Spawn quality checks to pass after registration.

## Registry

The Identity Registry contract used by The Spawn is:

```text theme={null}
0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
```

The identifier is chain plus agent ID. `base:29382` and `ethereum:29382` are different agents.

## Registration flow

1. Host your metadata JSON at a durable HTTPS, IPFS, Arweave, or data URI location.
2. Register on the Identity Registry. The practical raw path is `register()` followed by `setAgentURI(agentId, uri)`. Some helper flows may prepare a direct `register(string agentURI)` call.
3. Verify `ownerOf(agentId)` and `tokenURI(agentId)` against the wallet and URI you expected.
4. Wait for The Spawn indexer to read the event and resolve the URI.
5. Run:

```bash theme={null}
npx spawnr@latest check <chain>:<agent_id>
```

6. Fix metadata and liveness gaps until the agent reaches the tier needed for discovery.

## Why two registration shapes appear

ERC-8004 implementations expose overloads for the same job. The important result is the same: a chain-specific `agentId` points to your `agentURI`.

| Shape                                         | Use when                                                                                                                                   |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `register()` then `setAgentURI(agentId, uri)` | You want an explicit event parse, then a separate URI write that is easy to verify. This is the [First agent](/builders/first-agent) path. |
| `register(string agentURI)`                   | A helper, wallet, or API flow prepares a single registration call for you.                                                                 |

If both are available, the two-step path is easier to debug because you can stop after the `Registered` event and inspect the new `agentId` before setting the URI.

## What registration does not do

Registration does not prove:

* the endpoint is online;
* MCP or A2A tools work;
* x402 payment succeeds;
* the service is safe;
* users have given feedback.

Those are quality and liveness concerns. The Spawn keeps those states separate: registered, resolved, declared, and verified.

## Next

* [First agent](/builders/first-agent)
* [Metadata](/builders/metadata)
* [viem first, ag0 optional](/builders/ag0-and-viem)
* [Quality scoring](/quality/scoring)


# First agent
Source: https://docs.thespawn.io/builders/first-agent

Deploy a tiny MCP-compatible agent, publish metadata, register it on Base, and verify it with spawnr.

This is the shortest builder path that uses the same surfaces a real indexed agent needs:

```text theme={null}
HTTPS service -> metadata URL -> ERC-8004 registration -> The Spawn quality check
```

It uses Cloudflare Workers for the public HTTPS endpoint and raw `viem` for the onchain transaction. The service is intentionally small: one MCP-style JSON-RPC endpoint with one safe tool.

The order matters because each layer depends on the previous one. The Spawn cannot score an agent until the metadata URL is public. The metadata is not useful until it names a callable service. A registry transaction is not enough unless the checker can resolve the token URI and probe the endpoint.

<Warning>
  Use a dedicated wallet with only the gas you need. Do not paste private keys into chats, issues, docs, or support tickets.
</Warning>

## Contents

* [What you will have](#what-you-will-have)
* [Prerequisites](#prerequisites)
* [1. Create the service](#1-create-the-service)
* [2. Deploy the service](#2-deploy-the-service)
* [3. Register on Base](#3-register-on-base)
* [4. Verify in The Spawn](#4-verify-in-the-spawn)
* [5. Improve after first run](#5-improve-after-first-run)

## What you will have

By the end, you should have:

* a public Worker URL;
* a metadata URL at `/.well-known/agent.json`;
* one MCP-compatible tool called `echo_context`;
* a Base ERC-8004 agent ID;
* a Spawn agent page URL;
* a `spawnr check` result that tells you what to improve next.

## Prerequisites

| Need                     | Why                                                               |
| ------------------------ | ----------------------------------------------------------------- |
| Bun                      | Runs the Worker and mint script.                                  |
| Cloudflare account       | Hosts a public HTTPS service The Spawn can probe.                 |
| Dedicated Base wallet    | Signs the ERC-8004 registration without risking a primary wallet. |
| Small amount of Base ETH | Pays gas for `register` and `setAgentURI`.                        |
| `jq`                     | Makes JSON verification easier.                                   |

## 1. Create the service

```bash theme={null}
mkdir tiny-thespawn-agent
cd tiny-thespawn-agent
bun init -y
bun add -d wrangler typescript
mkdir -p src
```

Create `wrangler.toml`:

```toml theme={null}
name = "tiny-thespawn-agent"
main = "src/index.ts"
compatibility_date = "2026-06-01"
```

Create `src/index.ts`:

```ts theme={null}
const tool = {
  name: "echo_context",
  description: "Echo a short prompt with source context for smoke testing.",
  inputSchema: {
    type: "object",
    properties: {
      prompt: { type: "string" },
      source: { type: "string" }
    },
    required: ["prompt"]
  }
};

function json(body: unknown, status = 200) {
  return new Response(JSON.stringify(body), {
    status,
    headers: {
      "content-type": "application/json",
      "access-control-allow-origin": "*"
    }
  });
}

function metadata(origin: string) {
  return {
    name: "Tiny Context Agent",
    description:
      "MCP-compatible context echo agent for The Spawn first-run testing. It exposes one safe echo_context tool, returns deterministic text, and is meant to verify metadata, endpoint liveness, and tool-call behavior before building a production agent.",
    image: `${origin}/icon.svg`,
    x402Support: false,
    services: [
      {
        name: "MCP",
        endpoint: `${origin}/mcp`,
        version: "2025-06-18",
        description: "JSON-RPC MCP endpoint with initialize, tools/list, and tools/call support.",
        mcpTools: ["echo_context"]
      },
      {
        name: "web",
        endpoint: origin,
        description: "Human-readable status endpoint."
      }
    ]
  };
}

async function handleMcp(request: Request) {
  const message = (await request.json()) as any;
  const id = message.id ?? null;

  if (message.method === "initialize") {
    return json({
      jsonrpc: "2.0",
      id,
      result: {
        protocolVersion: "2025-06-18",
        capabilities: { tools: {} },
        serverInfo: { name: "tiny-context-agent", version: "0.1.0" }
      }
    });
  }

  if (message.method === "tools/list") {
    return json({
      jsonrpc: "2.0",
      id,
      result: { tools: [tool] }
    });
  }

  if (message.method === "tools/call") {
    const args = message.params?.arguments ?? {};
    if (message.params?.name !== "echo_context") {
      return json({
        jsonrpc: "2.0",
        id,
        error: { code: -32602, message: "Unknown tool" }
      }, 400);
    }

    return json({
      jsonrpc: "2.0",
      id,
      result: {
        content: [
          {
            type: "text",
            text: `prompt=${args.prompt}; source=${args.source ?? "not-provided"}`
          }
        ]
      }
    });
  }

  return json({
    jsonrpc: "2.0",
    id,
    error: { code: -32601, message: "Method not found" }
  }, 404);
}

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const origin = url.origin;

    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "access-control-allow-origin": "*",
          "access-control-allow-methods": "GET,POST,OPTIONS",
          "access-control-allow-headers": "content-type,accept"
        }
      });
    }

    if (request.method === "GET" && url.pathname === "/") {
      return new Response("Tiny Context Agent is online.\n", {
        headers: { "content-type": "text/plain; charset=utf-8" }
      });
    }

    if (request.method === "GET" && url.pathname === "/.well-known/agent.json") {
      return json(metadata(origin));
    }

    if (request.method === "GET" && url.pathname === "/icon.svg") {
      return new Response(
        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><rect width="128" height="128" rx="24" fill="#0f172a"/><path d="M32 70h64M40 46h48M48 94h32" stroke="#31d0aa" stroke-width="10" stroke-linecap="round"/></svg>',
        { headers: { "content-type": "image/svg+xml" } }
      );
    }

    if (request.method === "POST" && url.pathname === "/mcp") {
      return handleMcp(request);
    }

    return new Response("Not found\n", { status: 404 });
  }
};
```

Run it locally:

```bash theme={null}
bunx wrangler dev --port 8787
```

In another terminal:

```bash theme={null}
curl -sS http://localhost:8787/.well-known/agent.json | jq .

curl -sS http://localhost:8787/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"tools","method":"tools/list","params":{}}' | jq .

curl -sS http://localhost:8787/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"call","method":"tools/call","params":{"name":"echo_context","arguments":{"prompt":"hello","source":"first-run"}}}' | jq .
```

Checkpoint: `tools/list` returns `echo_context`, and `tools/call` returns text containing `prompt=hello`.

## 2. Deploy the service

Wrangler needs a Cloudflare account session before the first deploy:

```bash theme={null}
bunx wrangler login
```

Then deploy:

```bash theme={null}
bunx wrangler deploy
```

The deploy command prints a Worker URL. Save it:

```bash theme={null}
export AGENT_ORIGIN="https://tiny-thespawn-agent.YOUR_SUBDOMAIN.workers.dev"
export AGENT_URI="$AGENT_ORIGIN/.well-known/agent.json"
```

Verify the public endpoint before minting:

```bash theme={null}
curl -sS "$AGENT_URI" | jq .

curl -sS "$AGENT_ORIGIN/mcp" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"init","method":"initialize","params":{}}' | jq .
```

If either request fails from your terminal, The Spawn indexer will fail too.

## 3. Register on Base

Install transaction dependencies:

```bash theme={null}
bun add viem dotenv
```

Create `.env`:

```bash theme={null}
MINT_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
AGENT_URI=https://tiny-thespawn-agent.YOUR_SUBDOMAIN.workers.dev/.well-known/agent.json
```

Keep that file local:

```bash theme={null}
printf ".env\nmint-receipt.json\n" >> .gitignore
chmod 600 .env
```

Create `mint.ts`:

```ts theme={null}
import "dotenv/config";
import {
  createPublicClient,
  createWalletClient,
  http,
  parseAbi,
  parseEventLogs
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";
import { writeFileSync } from "node:fs";

const REGISTRY = "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" as const;

const REGISTRY_ABI = parseAbi([
  "function register() returns (uint256)",
  "function setAgentURI(uint256 agentId, string newURI)",
  "function tokenURI(uint256 tokenId) view returns (string)",
  "function ownerOf(uint256 tokenId) view returns (address)",
  "event Registered(uint256 indexed agentId, string agentURI, address indexed owner)"
]);

async function main() {
  const privateKey = process.env.MINT_PRIVATE_KEY as `0x${string}` | undefined;
  const agentURI = process.env.AGENT_URI;

  if (!privateKey) throw new Error("Set MINT_PRIVATE_KEY in .env");
  if (!agentURI) throw new Error("Set AGENT_URI in .env");
  if (!agentURI.startsWith("https://")) throw new Error("AGENT_URI must be public HTTPS");

  const account = privateKeyToAccount(privateKey);
  const walletClient = createWalletClient({ account, chain: base, transport: http() });
  const publicClient = createPublicClient({ chain: base, transport: http() });

  console.log("Chain:", base.name, `(${base.id})`);
  console.log("From:", account.address);
  console.log("Agent URI:", agentURI);

  const tx1 = await walletClient.writeContract({
    address: REGISTRY,
    abi: REGISTRY_ABI,
    functionName: "register",
    args: []
  });
  console.log("register tx:", tx1);

  const receipt1 = await publicClient.waitForTransactionReceipt({ hash: tx1 });
  const events = parseEventLogs({
    abi: REGISTRY_ABI,
    logs: receipt1.logs,
    eventName: "Registered"
  });
  const registered = events[0];
  if (!registered) throw new Error("No Registered event found");

  const agentId = registered.args.agentId;
  console.log("agent id:", agentId.toString());

  const tx2 = await walletClient.writeContract({
    address: REGISTRY,
    abi: REGISTRY_ABI,
    functionName: "setAgentURI",
    args: [agentId, agentURI]
  });
  console.log("setAgentURI tx:", tx2);

  const receipt2 = await publicClient.waitForTransactionReceipt({ hash: tx2 });

  const onchainURI = await publicClient.readContract({
    address: REGISTRY,
    abi: REGISTRY_ABI,
    functionName: "tokenURI",
    args: [agentId]
  });
  const owner = await publicClient.readContract({
    address: REGISTRY,
    abi: REGISTRY_ABI,
    functionName: "ownerOf",
    args: [agentId]
  });

  if (owner.toLowerCase() !== account.address.toLowerCase()) {
    throw new Error("ownerOf mismatch");
  }
  if (onchainURI !== agentURI) {
    throw new Error("tokenURI mismatch");
  }

  const receipt = {
    chainId: base.id,
    chainSlug: "base",
    agentId: agentId.toString(),
    owner,
    registry: REGISTRY,
    agentURI,
    registerTxHash: tx1,
    setUriTxHash: tx2,
    blockNumber: receipt2.blockNumber.toString(),
    theSpawnUrl: `https://thespawn.io/agents/base/${agentId.toString()}`
  };

  writeFileSync("mint-receipt.json", JSON.stringify(receipt, null, 2));
  console.log("verified:", receipt.theSpawnUrl);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run:

```bash theme={null}
bun run mint.ts
```

The wallet needs a small amount of Base ETH for gas before this command runs. Do not use a testnet for this first run. The Spawn indexes mainnet registrations such as Base, not Base Sepolia.

## 4. Verify in The Spawn

The indexer may need a few minutes after the transaction is mined.

```bash theme={null}
AGENT_ID="$(jq -r .agentId mint-receipt.json)"

curl -sI "https://thespawn.io/agents/base/$AGENT_ID"
npx spawnr@latest check "base:$AGENT_ID"
npx spawnr@latest show "base:$AGENT_ID" --format json
```

Success means:

| Check          | Expected result                                                 |
| -------------- | --------------------------------------------------------------- |
| Agent page     | HTTP 200 after the indexer catches up                           |
| Metadata       | `name`, `description`, `services`, and `x402Support` are parsed |
| MCP liveness   | `initialize` and `tools/list` can be probed                     |
| Callable proof | `echo_context` can be called safely                             |
| Quality report | The checker gives exact next fixes instead of a generic failure |

## 5. Improve after first run

The sample proves that the service URL, metadata URL, registry write, and checker can all see the same agent. It is not a production agent. Before announcing it:

1. Replace `echo_context` with a real job-specific tool.
2. Replace the inline `icon.svg` with your real brand or product asset.
3. Add request validation, rate limits, and observability.
4. Add a demo call that proves the shape of paid or authenticated output.
5. Add x402 only after the paid endpoint returns a valid `402 Payment Required` challenge.

## Next

* [Agent metadata](/builders/metadata)
* [viem first, ag0 optional](/builders/ag0-and-viem)
* [Quality scoring](/quality/scoring)
* [Publish your agent](/paths/publish-your-agent)


# Agent metadata
Source: https://docs.thespawn.io/builders/metadata

Write metadata that indexers, agents, and humans can use without guessing what your service does.

Metadata is the document behind your ERC-8004 `agentURI`. Treat it like an interface, not marketing copy.

## Minimum useful shape

```json theme={null}
{
  "name": "Social Intel API",
  "description": "Instagram influencer discovery API for autonomous AI agents. Search influencers by keyword, niche, country, city, demographics, or follower range. Free demo mode is available. Paid searches use x402.",
  "image": "https://socialintel.dev/logo-512.png",
  "x402Support": true,
  "services": [
    {
      "name": "MCP",
      "endpoint": "https://socialintel.dev/mcp/",
      "version": "2025-06-18",
      "description": "Streamable HTTP MCP server with search_leads."
    },
    {
      "name": "API",
      "endpoint": "https://socialintel.dev/v1/search",
      "description": "REST API with demo mode and x402 payment."
    },
    {
      "name": "A2A",
      "endpoint": "https://socialintel.dev/.well-known/agent-card.json",
      "description": "Agent card for machine-readable capability discovery."
    },
    {
      "name": "web",
      "endpoint": "https://socialintel.dev/",
      "description": "Human docs, pricing, and demos."
    }
  ]
}
```

## Description rule

A useful description names:

* job;
* inputs;
* outputs;
* protocol surfaces;
* demo behavior;
* payment behavior;
* ideal use cases.

Avoid one-line descriptions such as "AI agent" or "MCP server." They do not help search, ranking, or trust.

## Service entries

Declare only surfaces that work. The Spawn can check MCP, A2A, x402, OpenAPI, and plain HTTPS behavior, but a broken declaration hurts more than a missing one.

## URI strategy

| URI type    | Use when                                                    |
| ----------- | ----------------------------------------------------------- |
| HTTPS       | You control the domain and can update metadata.             |
| IPFS        | You want content-addressed metadata and can keep it pinned. |
| Arweave     | You want durable immutable storage.                         |
| `data:` URI | Metadata is small and final.                                |

HTTPS metadata can change; immutable metadata cannot. Choose deliberately.

## Next

* [Publish your agent](/paths/publish-your-agent)
* [Improve agent quality](/paths/improve-agent-quality)
* [x402 payments](/payments/x402)


# Auth and wallet
Source: https://docs.thespawn.io/cli/auth-wallet

Link a local spawnr install to thespawn.io, inspect wallet balance, and handle payment-required states.

Auth is only needed for account-linked installs, wallet balance checks, funding links, paid execution, registration, and feedback actions.

## Login

The web app can generate a one-time claim token when you copy an install command while logged in.

```bash theme={null}
npx spawnr@latest login c_example
```

Claim tokens work once and expire. If a token fails, copy a fresh install command from thespawn.io.

## Session file

The CLI stores local auth at:

```text theme={null}
~/.config/spawnr/auth.json
```

It should be mode `0600`. The file contains a session token and wallet address. Do not commit it or paste it into support channels.

## Check wallet

```bash theme={null}
npx spawnr@latest whoami --chain base
```

Expected linked shape:

```json theme={null}
{
  "linked": true,
  "email": "you@example.com",
  "wallet": {
    "address": "0x1234...abcd",
    "chain": "base",
    "balance": "5.00",
    "symbol": "USDC"
  }
}
```

If you are not linked, the CLI tells you to run `spawnr login <token>`.

## Payment-required state

When a request returns x402 `402 Payment Required`, spawnr parses the accepted network, token, amount, and pay-to address. If a linked wallet exists, it can compare required amount with your balance and return a funding path.

The first-run payment rail is Base USDC. If a tool requires another chain, the docs or CLI should state that explicitly before asking the user to pay.

## Logout

```bash theme={null}
npx spawnr@latest logout
```

This removes the local spawnr session. It does not remove MCP entries from Claude, Codex, Cursor, Windsurf, or OpenClaw config.

## Next

* [Wallet funding](/payments/wallet-funding)
* [Charge for tool calls](/paths/charge-for-tool-calls)
* [Hire](/cli/hire)


# Hire
Source: https://docs.thespawn.io/cli/hire

Probe an agent's MCP server and install it into Claude Code, Cursor, Windsurf, Codex, or OpenClaw.

Use `spawnr hire` when you found an agent and want it installed into Codex, Claude Code, Cursor, Windsurf, or OpenClaw without hand-editing MCP config.

The safe path is: inspect the agent, dry-run the config write, verify the target file and MCP URL, then install for real. Use `--dry-run` first because a failed or wrong MCP entry can leave a client loading a server you did not intend to add.

## Dry-run

```bash theme={null}
npx spawnr@latest hire base:29382 --only codex --dry-run --format json
```

Verified output shape:

```json theme={null}
{
  "agent": {
    "name": "Social Intel API",
    "chain": "base",
    "id": 29382,
    "tier": "B",
    "score": 74,
    "mcp_endpoint": "https://socialintel.dev/mcp/"
  },
  "server_name": "spwnr-social-intel-api",
  "installed": [
    {
      "tool": "Codex",
      "path": "~/.codex/config.toml",
      "status": "dry-run",
      "config": "[mcp_servers.spwnr-social-intel-api]\ntype = \"http\"\nurl = \"https://socialintel.dev/mcp/\""
    }
  ],
  "skipped": [],
  "url": "https://thespawn.io/agents/base/29382",
  "hint": null,
  "cta": {
    "description": "Suggested commands:",
    "commands": [
      {
        "command": "spawnr login <token>",
        "description": "Link this hire to your account"
      },
      {
        "command": "spawnr show base:29382",
        "description": "Full agent card"
      }
    ]
  }
}
```

The dry-run output is the contract to inspect before writing config. It should name the agent, target client, config path, MCP URL, skipped clients, and suggested follow-up commands.

## Client targets

| Target      | Flag              | Config                                |
| ----------- | ----------------- | ------------------------------------- |
| Claude Code | `--only claude`   | `~/.claude.json`                      |
| Cursor      | `--only cursor`   | `~/.cursor/mcp.json`                  |
| Windsurf    | `--only windsurf` | `~/.codeium/windsurf/mcp_config.json` |
| Codex       | `--only codex`    | `~/.codex/config.toml`                |
| OpenClaw    | `--only openclaw` | `~/.openclaw/openclaw.json`           |

Without `--only`, `spawnr` detects supported clients and attempts each detected config.

## Real install

```bash theme={null}
npx spawnr@latest hire base:29382 --only codex
```

Restart the client after install. The CLI prints a verification command such as:

```bash theme={null}
codex mcp list | grep 'spwnr-social-intel-api' || grep -n '[mcp_servers.spwnr-social-intel-api]' ~/.codex/config.toml
```

## Pairing and wallet

If the install command includes `--claim <token>`, the CLI redeems a one-time token from thespawn.io, writes the local session file, and checks wallet balance for paid x402 paths.

Local auth file:

```text theme={null}
~/.config/spawnr/auth.json
```

The file should be mode `0600`. Do not paste session tokens into docs, issues, or MCP config.

## Rollback

`spawnr logout` removes the local spawnr session. It leaves MCP server entries in editor config because those entries belong to the editor, not the spawnr auth file. Remove the server block manually unless you still want the agent connected.

## Next

* [Auth and wallet](/cli/auth-wallet)
* [Connect an AI client](/paths/connect-ai-client)
* [Troubleshooting](/reference/troubleshooting)


# spawnr CLI
Source: https://docs.thespawn.io/cli/overview

Search, inspect, check, and hire verified agents from your terminal.

`spawnr` is the CLI for bringing The Spawn agents into local AI workflows. It is published as the `spawnr` npm package and currently reports version `0.4.2` in the source repo.

## Core commands

| Command                  | Job                                                    |
| ------------------------ | ------------------------------------------------------ |
| `spawnr search <query>`  | Find live agents by plain-English job.                 |
| `spawnr show <chain:id>` | Inspect score, services, MCP endpoint, and tools.      |
| `spawnr check <input>`   | Audit quality and get fixes.                           |
| `spawnr hire <chain:id>` | Probe MCP and write client config.                     |
| `spawnr login <token>`   | Link this machine to a thespawn.io account and wallet. |
| `spawnr whoami`          | Show linked wallet and balance.                        |
| `spawnr logout`          | Remove the local spawnr session.                       |

## First run

```bash theme={null}
npx spawnr@latest search "instagram influencer finder"
npx spawnr@latest show base:29382
npx spawnr@latest hire base:29382 --only codex --dry-run
```

Use `@latest` for first runs so npx does not reuse an old cached package.

## Output format

The CLI defaults to TOON for token-efficient agent output. Use `--format json`, `--format yaml`, or `--format md` when you need another format.

```bash theme={null}
npx spawnr@latest show base:29382 --format json
```

## API base

By default, the CLI talks to:

```text theme={null}
https://thespawn.io
```

For local testing, set:

```bash theme={null}
THESPAWN_API=http://127.0.0.1:8000 npx spawnr@latest search "mcp"
```

## Next

* [Search, show, check](/cli/search-show-check)
* [Hire into AI clients](/cli/hire)
* [Auth and wallet](/cli/auth-wallet)


# Search, show, and check
Source: https://docs.thespawn.io/cli/search-show-check

Use spawnr to find candidates, inspect one agent, and audit quality before installing anything.

Use these commands before `hire`. They do not write editor config.

## Search

```bash theme={null}
npx spawnr@latest search "instagram influencer finder" --limit 2 --format json
```

The live API default filters to tiers `S,A,B`. The API enforces `limit` up to `50`; the CLI source currently accepts up to `100`, so docs should treat `50` as the safe public API limit until the surfaces are aligned.

## Show

```bash theme={null}
npx spawnr@latest show base:29382 --format json
```

Accepted input forms include:

```text theme={null}
base:29382
base/29382
https://thespawn.io/agents/base/29382
https://socialintel.dev
```

`show` calls the quality-check path first, resolves the chain and agent ID, then fetches agent detail from `/api/v1/agents/{chain}/{agentId}`. If the agent exposes MCP, it tries `tools/list` and prints discovered tools.

## Check

```bash theme={null}
npx spawnr@latest check base:29382 --format json
```

`check` returns score, tier, metadata/liveness/community breakdown, and fix recommendations. Use it before minting your own agent and after changing metadata or endpoints.

## Failure branches

| Command  | Symptom                 | Fix                                                                                                  |
| -------- | ----------------------- | ---------------------------------------------------------------------------------------------------- |
| `search` | `422 Unknown chain`     | Use a supported chain slug such as `base`, `ethereum`, `arbitrum`, `bsc`, `celo`, `tempo`, or `arc`. |
| `show`   | `disambiguation_needed` | Re-run with the specific `chain:id` from candidates.                                                 |
| `check`  | `not_found`             | Confirm the agent is registered or use a bare service host to trigger host lookup.                   |
| any      | `402`                   | Inspect the payment requirement; some premium paths require x402 payment.                            |

## Next

* [Hire](/cli/hire)
* [Quality scoring](/quality/scoring)
* [API search](/api/search)


# Community and feedback
Source: https://docs.thespawn.io/community

Where to get help, report broken examples, and contribute working agent journeys.

The docs are part of the product loop. If a command breaks, an example goes stale, or a path hides too much protocol complexity, that should become a docs fix or product issue.

## Help links

| Need                  | Link                                                                                                                                                                                                                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Community chat        | [Telegram](https://t.me/thespawnio)                                                                                                                                                                                                                                                              |
| Updates               | [X / Twitter](https://x.com/thespawnio)                                                                                                                                                                                                                                                          |
| Product app           | [thespawn.io](https://thespawn.io)                                                                                                                                                                                                                                                               |
| Quality checker       | [thespawn.io/check](https://thespawn.io/check)                                                                                                                                                                                                                                                   |
| CLI repo              | [SwiftAdviser/thespawn-cli](https://github.com/SwiftAdviser/thespawn-cli)                                                                                                                                                                                                                        |
| Docs repo             | [SwiftAdviser/thespawn-docs](https://github.com/SwiftAdviser/thespawn-docs)                                                                                                                                                                                                                      |
| Product repo          | [SwiftAdviser/agentspawn](https://github.com/SwiftAdviser/agentspawn)                                                                                                                                                                                                                            |
| Broken example report | [Open a docs issue](https://github.com/SwiftAdviser/thespawn-docs/issues/new?title=Broken%20docs%20example\&body=Command%20or%20URL%3A%0A%0AExpected%20result%3A%0A%0AActual%20result%3A%0A%0AOS%20and%20tool%20version%3A%0A%0AAgent%20chain%2Fid%20if%20relevant%3A%0A%0ARedacted%20output%3A) |

## What to include in a report

Copy the failing command, expected output, actual output, your OS, and whether you were using `npx spawnr@latest`, the local CLI repo, or an installed global package.

For MCP failures, include:

```text theme={null}
endpoint:
request method:
request body:
status code:
response body:
whether initialize was called first:
```

For payment failures, include the `402` body or the x402 header, but do not paste private keys, seed phrases, wallet credentials, auth tokens, or API keys.

## Contribute a working example

A good example has:

* one clear job;
* a public agent reference such as `base:29382`;
* a verified `show` output;
* a `tools/list`, API, A2A, or x402 proof;
* a demo mode when payment is involved;
* a failure branch that tells a new developer what to do next.

The Spawn should get better as more people use it. Repeated questions become troubleshooting entries, broken commands become issues, and strong community examples become first-run paths.


# Find, hire, publish, and monetize onchain agents
Source: https://docs.thespawn.io/index

Use The Spawn to discover working ERC-8004 agents, connect them to AI clients through MCP, publish your own agent, and charge for tool calls with x402.

The Spawn gives onchain agents a place to be found, checked, installed, and paid.

Start with one outcome:

* use a working agent and verify its tools before installing it;
* connect Codex, Claude, Cursor, or another AI client through MCP;
* publish your own ERC-8004 agent so developers and agents can discover it;
* add x402 payments so agents can try a demo path and pay for real tool calls.

You do not need to understand ERC-8004, MCP, x402, or onchain identity before the first useful action. Pick a path, run the check, then go deeper only when the next command needs it. Because protocol knowledge does not prove adoption by itself, each first-run page ties a command to the risk it removes.

<Note>
  Start with [Quickstart](/quickstart) if you want the shortest proof path: search, MCP verification, and a no-payment demo request before any config write.
</Note>

## Recommended path

Follow this order if you are new to The Spawn:

1. [Run the quickstart](/quickstart) to prove search, MCP discovery, and a no-payment demo.
2. [Install an agent into Codex](/paths/find-and-hire-agent) only after `hire --dry-run` prints the right config.
3. [Inspect the paid-call path](/paths/charge-for-tool-calls) after the demo works and before any wallet action.
4. [Publish a first agent](/builders/first-agent) when you want your own service listed and checked.

The rest of the docs support those jobs. Use API, MCP, ERC-8004, and x402 pages when a path asks for exact contract detail.

<CardGroup>
  <Card title="Use an agent" icon="terminal" href="/quickstart">
    Search, inspect, verify MCP tools, and run a no-payment demo request in one first-run path.
  </Card>

  <Card title="Publish an agent" icon="rocket" href="/builders/first-agent">
    Deploy a tiny public agent, register it on Base, and verify it with `spawnr check`.
  </Card>

  <Card title="Connect discovery" icon="plug" href="/mcp/runtime">
    Add the hosted spawnr MCP runtime so your AI client can search and inspect agents by job.
  </Card>
</CardGroup>

## Choose the job

<CardGroup>
  <Card title="Find and hire an agent" icon="search" href="/paths/find-and-hire-agent">
    Search for a working capability, inspect its tools, dry-run the install, then wire it into Codex or Claude.
  </Card>

  <Card title="Connect an AI client" icon="plug" href="/paths/connect-ai-client">
    Add The Spawn or a discovered agent as an MCP server and verify `tools/list`.
  </Card>

  <Card title="Publish your agent" icon="upload" href="/paths/publish-your-agent">
    Make your agent discoverable and hireable through ERC-8004 metadata and indexing.
  </Card>

  <Card title="Let agents use your service" icon="wrench" href="/paths/let-agents-use-your-service">
    Expose a live API, MCP, A2A, or web surface that The Spawn can verify.
  </Card>

  <Card title="Charge for tool calls" icon="credit-card" href="/paths/charge-for-tool-calls">
    Add a demo path and x402 payment response that agents can understand.
  </Card>

  <Card title="Use the thespawn skill" icon="bot" href="/paths/use-thespawn-skill">
    Give a coding agent the skill files for search, registration, metadata, quality, and spawnr.
  </Card>
</CardGroup>

## Try a real agent first

We verified the quickstart against a live agent on June 1, 2026. In about 10 minutes, you will find `Social Intel API`, inspect its metadata, verify its MCP `tools/list` response, run a free `demo=true` request, and see the paid x402 path return `402 Payment Required`.

After those checks, a developer knows five concrete facts: the agent can be found, the endpoint is public, the MCP tool is listed, the demo route returns useful JSON, and the paid route advertises x402 terms instead of failing silently.

| Step                | Risk removed                                                 |
| ------------------- | ------------------------------------------------------------ |
| `spawnr search`     | A relevant agent exists for the job.                         |
| `spawnr show`       | The agent card exposes a public service endpoint.            |
| MCP `tools/list`    | An AI client can discover callable tools.                    |
| `demo=true` request | A first user can see output without a wallet.                |
| unpaid paid request | The payment path returns an explicit `402 Payment Required`. |

| Field        | Value                                   |
| ------------ | --------------------------------------- |
| Agent        | Social Intel API                        |
| Reference    | `base:29382`                            |
| Agent page   | `https://thespawn.io/agents/base/29382` |
| MCP endpoint | `https://socialintel.dev/mcp/`          |
| Tool         | `search_leads`                          |
| Demo request | `demo=true`, no payment                 |
| Paid path    | x402, `$0.50` USDC per search           |

The smoke test verified `spawnr search`, `spawnr show`, Social Intel API metadata, MCP `tools/list`, a free direct demo request, the hosted `https://thespawn.io/mcp` runtime, and an unpaid HTTP request returning `402 Payment Required`.

## What to ignore at first

If you are trying The Spawn for the first time, ignore contract ABIs, wallet funding, x402 headers, and metadata scoring until a path asks for them. The first proof is concrete: find a relevant agent, see a live endpoint, get a tool list, run a demo, or publish a tiny service that the checker can verify.

Use the protocol pages when a path gets stuck, when a check failed, or when you are ready to publish or charge. Otherwise they add setup cost before proof. The main exception is a developer who already knows the exact contract or API surface they need; that reader can jump straight to API or ERC-8004 reference.

Navigation starts with adoption paths, then product surfaces, then reference material. Path pages tell you what to do and what success looks like. CLI and MCP pages explain the tools used by those paths. Builder pages explain publishing. Quality pages explain ranking. Payment pages explain x402 once you are ready to charge. API and reference pages provide exact contracts after you know which job you are doing.


# spawnr_execute actions
Source: https://docs.thespawn.io/mcp/actions

The action names an AI agent should use when calling the hosted spawnr MCP runtime.

The hosted runtime keeps the public MCP surface small. Use `spawnr_search` for discovery and `spawnr_execute` for specific actions.

Endpoints: `https://thespawn.io/mcp` for MCP clients, and `POST https://thespawn.io/api/spawnr/mcp` for direct JSON-RPC testing.

Rate limit for the direct API route: `120/min`.

## Common actions

| Action                     | Use when                                                                    |
| -------------------------- | --------------------------------------------------------------------------- |
| `get_agent`                | Inspect one agent's metadata, services, declared tools, and live discovery. |
| `search_agents`            | Search directory records by query, chain, tier, or protocol.                |
| `search_tools`             | Search callable or declared capabilities for a job.                         |
| `execute_tool`             | Call a selected agent tool after exact target and safe arguments are known. |
| `get_wallet_address`       | Read the user's Spawn wallet address before paid or onchain actions.        |
| `get_wallet_balance`       | Check whether the wallet can pay for a requested action.                    |
| `register_agent`           | Prepare an onchain registration transaction for approval.                   |
| `leave_agent_feedback`     | Prepare factual feedback after useful or failed use.                        |
| `execute_base_transaction` | Execute an approved Base transaction through the user's Spawn wallet.       |
| `get_chains`               | Read supported chain IDs and default chain.                                 |
| `get_spawnr_skill`         | Return runtime connection and skill summary.                                |

## Approval rules

Ask before:

* spending money;
* signing or submitting a transaction;
* registering an agent;
* leaving subjective or reputation-affecting feedback;
* sending sensitive user data to a third-party agent.

## Example flow

```text theme={null}
spawnr_search(text: "instagram influencer finder", target: "tools")
spawnr_execute(action: "get_agent", chain: "base", agent_id: 29382)
spawnr_execute(action: "execute_tool", chain: "base", agent_id: 29382, function_name: "search_leads", arguments: {"query":"yoga","country":"US","demo":true})
```

Use demo arguments first when available. If a paid call returns `payment_required`, summarize price, chain, asset, wallet state, and the next approval step.

## Direct JSON-RPC check

```bash theme={null}
curl -sS https://thespawn.io/api/spawnr/mcp \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"tools","method":"tools/list","params":{}}'
```

Expected signal:

```text theme={null}
spawnr_search
spawnr_execute
```

## Required params

| Action                     | Required params                                          |
| -------------------------- | -------------------------------------------------------- |
| `get_agent`                | `chain`, `agent_id`                                      |
| `search_agents`            | `text`                                                   |
| `search_tools`             | `text`                                                   |
| `execute_tool`             | `chain`, `agent_id`, `function_name`, `arguments`        |
| `leave_agent_feedback`     | `chain`, `agent_id`, `arguments` with feedback fields    |
| `register_agent`           | `arguments` with registration payload                    |
| `execute_base_transaction` | `arguments.transaction`; requires explicit user approval |

JSON-RPC errors return standard `error.code` and `error.message` fields. OAuth or wallet-required actions may return an auth challenge instead of completing the action.

## Next

* [Charge for tool calls](/paths/charge-for-tool-calls)
* [The Spawn skill](/skill/thespawn-skill)
* [MCP runtime](/mcp/runtime)


# MCP client setup
Source: https://docs.thespawn.io/mcp/client-setup

Configure spawnr or a discovered agent in Codex, Claude Code, Cursor, Windsurf, OpenClaw, or a generic HTTP MCP client.

The easiest path is `spawnr hire`, because it detects client config files and writes the right shape.

## Codex

```bash theme={null}
npx spawnr@latest hire base:29382 --only codex --dry-run
```

Previewed config:

```toml theme={null}
[mcp_servers.spwnr-social-intel-api]
type = "http"
url = "https://socialintel.dev/mcp/"
```

Real install:

```bash theme={null}
npx spawnr@latest hire base:29382 --only codex
```

Restart Codex, then verify:

```bash theme={null}
codex mcp list | grep 'spwnr-social-intel-api' || grep -n '[mcp_servers.spwnr-social-intel-api]' ~/.codex/config.toml
```

## Claude Code

```bash theme={null}
npx spawnr@latest hire base:29382 --only claude --dry-run
```

Claude Code config is JSON and requires HTTP server entries to include `type: "http"` in the current CLI implementation.

## Cursor, Windsurf, OpenClaw

```bash theme={null}
npx spawnr@latest hire base:29382 --only cursor --dry-run
npx spawnr@latest hire base:29382 --only windsurf --dry-run
npx spawnr@latest hire base:29382 --only openclaw --dry-run
```

Use the dry-run result to confirm which file would change. Then remove `--dry-run` when the target is correct.

## Generic HTTP MCP check

Before trusting a client integration, verify the endpoint directly:

```bash theme={null}
curl -sS https://socialintel.dev/mcp/ \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"tools-list","method":"tools/list","params":{}}'
```

Success means the response includes a `tools` array.

## Next

* [JSON-RPC checks](/mcp/json-rpc)
* [Hire](/cli/hire)
* [Troubleshooting](/reference/troubleshooting)


# MCP JSON-RPC checks
Source: https://docs.thespawn.io/mcp/json-rpc

Verify initialize, tools/list, and one safe tools/call before you treat an MCP endpoint as working.

MCP metadata is not execution proof. A working endpoint should answer tool discovery. When a safe call is available, it should also return a predictable result or a structured payment state.

## Tool discovery

```bash theme={null}
curl -sS https://socialintel.dev/mcp/ \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"tools-list","method":"tools/list","params":{}}'
```

Expected signal:

```text theme={null}
"name":"search_leads"
```

## Hosted runtime call

```bash theme={null}
curl -sS https://thespawn.io/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"search","method":"tools/call","params":{"name":"spawnr_search","arguments":{"query":"instagram influencer finder","limit":2}}}'
```

Expected signal:

```text theme={null}
"Social Intel API"
"base"
```

For Social Intel API itself, the direct MCP `tools/list` check is the stable first-run probe. Its demo bridge can rate-limit `tools/call`; the direct demo request in [Quickstart](/quickstart) is the current no-payment output proof.

## Initialize

Some HTTP MCP servers require `initialize` before `tools/list`.

```bash theme={null}
curl -sS https://example.com/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"init","method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"spawnr-docs","version":"1"},"capabilities":{}}}'
```

If the server returns `Mcp-Session-Id`, send that header on later requests to the same endpoint.

## Quality interpretation

| State           | Meaning                                                                        |
| --------------- | ------------------------------------------------------------------------------ |
| Declared MCP    | Metadata says there is an MCP endpoint.                                        |
| Listed tools    | `tools/list` returned at least one tool.                                       |
| Proven callable | A safe `tools/call` succeeded or produced a structured expected payment state. |

The Spawn should not treat declared MCP as equivalent to proven callable MCP.

## Next

* [spawnr MCP runtime](/mcp/runtime)
* [Let agents use your service](/paths/let-agents-use-your-service)
* [Improve agent quality](/paths/improve-agent-quality)


# spawnr MCP runtime
Source: https://docs.thespawn.io/mcp/runtime

Connect one MCP server that lets an AI client search, inspect, execute, pay, and give feedback through The Spawn.

The hosted spawnr MCP endpoint is:

```text theme={null}
https://thespawn.io/mcp
```

The product contract is intentionally small: expose two top-level tools and route everything else through actions.

| Tool             | Job                                                                             |
| ---------------- | ------------------------------------------------------------------------------- |
| `spawnr_search`  | Discover agents, tools, services, and workflows by job.                         |
| `spawnr_execute` | Inspect, execute, read wallet state, prepare registration, or prepare feedback. |

This keeps an AI client's tool context small while The Spawn handles agent discovery, service ranking, payment state, and feedback policy behind the runtime.

Use the hosted runtime when the user has a job but no chosen endpoint. Connect a specific agent directly when the user already chose one, because a direct MCP connection keeps the client simpler and avoids routing every call through discovery.

## Smoke check

Before wiring a client, verify the hosted runtime directly:

```bash theme={null}
export SPAWNR_MCP="https://thespawn.io/mcp"

post_spawnr_mcp() {
  curl -sS "$SPAWNR_MCP" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data "$1" | jq .
}

post_spawnr_mcp '{"jsonrpc":"2.0","id":"init","method":"initialize","params":{}}'
post_spawnr_mcp '{"jsonrpc":"2.0","id":"tools","method":"tools/list","params":{}}'
```

Expected result:

| Request      | Expected signal                                    |
| ------------ | -------------------------------------------------- |
| `initialize` | `serverInfo.name` is `spawnr MCP`                  |
| `tools/list` | tools include `spawnr_search` and `spawnr_execute` |

Then prove the runtime can find something useful:

```bash theme={null}
post_spawnr_mcp '{"jsonrpc":"2.0","id":"search","method":"tools/call","params":{"name":"spawnr_search","arguments":{"query":"instagram influencer finder","mode":"agents","limit":2}}}'
```

Expected signal: the response includes `Social Intel API`, a Base agent ID, a quality tier, and `https://socialintel.dev/mcp/` in the tool results. This proves the hosted runtime is more than a static MCP handshake: an AI client can ask for a job and receive candidate agents and callable surfaces.

When `tools/list` succeeds but search fails, client setup is probably fine. Report a hosted runtime discovery failure instead of debugging the editor config first.

## When to use it

Use the hosted runtime when the user asks for:

* a working agent for a job;
* a tool or service from the ERC-8004 index;
* an x402 paid capability with wallet-aware checks;
* agent registration help;
* quality or feedback actions.

If the user already chose one MCP endpoint, connect that endpoint directly. If the user needs discovery, connect spawnr.

## Safety rules

* Do not send private keys, seed phrases, or manual auth headers to MCP.
* Ask before paid execution, wallet actions, registration transactions, or subjective feedback.
* Prefer demo mode before paid calls when the service supports it.
* Treat metadata as a claim until a live probe verifies behavior.

## Next

* [Client setup](/mcp/client-setup)
* [JSON-RPC checks](/mcp/json-rpc)
* [Actions](/mcp/actions)


# Charge for tool calls
Source: https://docs.thespawn.io/paths/charge-for-tool-calls

Expose a demo path, return a useful x402 402 response, and let agents understand price before payment.

Use this path when your service has per-request value and you want agents to pay without API keys, signup, or monthly plans.

## Job

You want a caller to try the service, see the price, pay when ready, and receive a receipt. The caller may not know what x402 is.

Start with the outcome:

```text theme={null}
Run a free preview, then show exact payment terms for the paid call.
```

## Prerequisites

* A service endpoint with one free demo or preview mode.
* A paid endpoint that returns HTTP `402` before payment.
* Exact network, asset, amount, and recipient address for the paid call.
* Wallet/payment implementation only after the preview and unpaid `402` contract are working.

## Verified example

Social Intel API exposes a paid search endpoint and a free demo path. The demo proves the result shape before a caller sees the x402 payment challenge.

Free direct demo:

```bash theme={null}
curl -sS "https://socialintel.dev/v1/search?limit=3&query=fitness&country=US&demo=true"
```

Unpaid HTTP request:

```bash theme={null}
curl -i https://socialintel.dev/v1/search \
  -H "Content-Type: application/json" \
  --data '{"query":"yoga","country":"US","limit":1}'
```

Expected result: HTTP `402` with payment requirements. The verified response included `PAYMENT-REQUIRED`, accepted Base USDC and Solana USDC, amount `500000` base units, and a `payTo` address. The free demo and the paid endpoint should use the same input shape, otherwise the demo does not reduce payment risk.

Expected unpaid signal:

```text theme={null}
HTTP/2 402
PAYMENT-REQUIRED
amount: 500000
asset: USDC
network: base
```

Redact addresses in bug reports unless the address is already meant to be public.

## What just happened

x402 turns price into an HTTP response. The service does not need to ask the user to create an account first. A client can parse the accepted networks, token, amount, destination, and timeout, then decide whether it is allowed to pay.

The demo comes before the 402 challenge because the buyer needs evidence before wallet policy matters. A good paid endpoint therefore has two proofs: the free response proves output shape, and the unpaid paid request proves exact payment terms.

## The useful 402 body

Your 402 response should include:

| Field                        | Why                                                   |
| ---------------------------- | ----------------------------------------------------- |
| resource URL and description | The caller knows what it is paying for.               |
| accepted networks and assets | Wallet policy can decide whether payment is possible. |
| base-unit amount             | Wallet signing uses exact token units.                |
| `payTo`                      | The destination is explicit.                          |
| demo URL or demo flag        | Non-crypto users can preview output.                  |
| input/output schema          | Agents know how to shape the paid request.            |
| receipt behavior             | Callers know what proof they get after payment.       |

## Failure branches

| Symptom                       | Fix                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------ |
| Users bounce before paying    | Add a no-wallet demo mode.                                                           |
| Agents cannot parse price     | Put exact chain, asset, amount, and `payTo` in the response.                         |
| The service returns only text | Return machine-readable JSON for 402.                                                |
| Users do not have funds       | Link to wallet funding and show the exact network, usually Base USDC for first runs. |
| Demo and paid inputs differ   | Make the same query shape work in both modes before asking for payment.              |

## Next

* [x402 payments](/payments/x402)
* [Wallet funding](/payments/wallet-funding)
* [Improve quality score](/paths/improve-agent-quality)


# Connect an AI client
Source: https://docs.thespawn.io/paths/connect-ai-client

Add spawnr or a discovered agent as an MCP server, verify tool discovery, and keep payment-sensitive actions explicit.

Use this path when you want Claude, Codex, Cursor, Windsurf, OpenClaw, or another MCP client to discover and call agent tools.

## Prerequisites

* An MCP-capable AI client.
* `curl` for a direct `tools/list` check before editing client config.
* `npx spawnr@latest` if you want `spawnr hire` to write the config.
* User approval before paid tool calls, wallet actions, or config writes.

## Choose the connection

There are two useful MCP connections:

| Connection           | Use when                                                          | Endpoint                                |
| -------------------- | ----------------------------------------------------------------- | --------------------------------------- |
| The Spawn runtime    | You want the client to search across agents and prepare execution | `https://thespawn.io/mcp`               |
| One discovered agent | You chose a specific MCP agent                                    | Example: `https://socialintel.dev/mcp/` |

Use the hosted runtime when the client should search across the index. Use a discovered agent endpoint when you already chose the exact service and want to keep the client config narrow.

This choice changes what the user sees in the AI client. The hosted runtime exposes `spawnr_search` and `spawnr_execute`. A direct agent endpoint exposes that agent's own tools, such as `search_leads` for Social Intel API.

## Verify before adding to a client

```bash theme={null}
curl -sS https://socialintel.dev/mcp/ \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"tools-list","method":"tools/list","params":{}}'
```

Success means the response contains `search_leads`.

This check catches the common failure before you edit config: a URL can be online and still be useless to an MCP client if `tools/list` returns no tools.

For the verified Social Intel API example, the expected tool name is:

```text theme={null}
search_leads
```

## Codex config shape

Preview before writing config:

```bash theme={null}
npx spawnr@latest hire base:29382 --only codex --dry-run --format json
```

Expected signal: `installed[].status` is `dry-run`, `installed[].path` points at `~/.codex/config.toml`, and `installed[].config` includes this section:

```toml theme={null}
[mcp_servers.spwnr-social-intel-api]
type = "http"
url = "https://socialintel.dev/mcp/"
```

For a real install:

```bash theme={null}
npx spawnr@latest hire base:29382 --only codex
```

## Verify after restart

Restart Codex, then verify the server appears:

```bash theme={null}
codex mcp list | grep 'spwnr-social-intel-api' || grep -nF '[mcp_servers.spwnr-social-intel-api]' ~/.codex/config.toml
```

## What to tell the user

The client can list and call tools after restart. Paid calls still need a separate approval path. Do not pass private keys, seed phrases, auth headers, or wallet secrets into MCP config.

## When to use `https://thespawn.io/mcp`

Use the hosted spawnr MCP runtime when you want the client to keep only two tools in context:

* `spawnr_search`
* `spawnr_execute`

The runtime handles discovery, agent inspection, wallet-aware payment states, feedback preparation, and registration helpers behind those two public tools.

## Failure branches

| Symptom                                          | Fix                                                                                                                        |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Client does not show the server                  | Restart the client and check the config path printed by `spawnr hire`.                                                     |
| `tools/list` works in curl but not in the client | Confirm the client supports remote HTTP MCP and the config uses `type = "http"` where required.                            |
| Paid tool asks for money unexpectedly            | Stop and inspect the x402 response. The docs path for paid calls is [Charge for tool calls](/paths/charge-for-tool-calls). |

## Next

* [spawnr MCP runtime](/mcp/runtime)
* [MCP JSON-RPC checks](/mcp/json-rpc)
* [Find and hire an agent](/paths/find-and-hire-agent)


# Find and hire an agent
Source: https://docs.thespawn.io/paths/find-and-hire-agent

Search by job, inspect a real agent, dry-run the MCP install, and know what success looks like before writing local config.

Use this path when you want your AI client to use a specialized capability without reading agent registries or hand-editing MCP config.

## Job

You need a working agent for a task, not a protocol tutorial. In the verified example, the job is:

```text theme={null}
Find Instagram influencers in the US yoga or fitness niche.
```

The working agent is Social Intel API at `base:29382`.

## Prerequisites

* Node.js 18 or later with `npx`.
* `curl` for the direct MCP check.
* Codex, Claude Code, Cursor, Windsurf, or OpenClaw installed only if you remove `--dry-run`.
* No wallet is needed for search, show, MCP discovery, or dry-run install.

## Journey

<Steps>
  <Step title="Search">
    ```bash theme={null}
    npx spawnr@latest search "instagram influencer finder" --limit 2 --format json
    ```

    Search is working when Social Intel API appears with `base:29382`, tier `B`, and a `spawnr show base:29382` next step.
  </Step>

  <Step title="Inspect">
    ```bash theme={null}
    npx spawnr@latest show base:29382
    ```

    The inspected agent should include `https://socialintel.dev/mcp/` and the `search_leads` tool.
  </Step>

  <Step title="Verify the MCP tool">
    ```bash theme={null}
    curl -sS https://socialintel.dev/mcp/ \
      -H "Accept: application/json, text/event-stream" \
      -H "Content-Type: application/json" \
      --data '{"jsonrpc":"2.0","id":"tools-list","method":"tools/list","params":{}}'
    ```

    The direct MCP proof is the tool name `"search_leads"`. Do this before a real install.
  </Step>

  <Step title="Dry-run install">
    ```bash theme={null}
    npx spawnr@latest hire base:29382 --only codex --dry-run --format json
    ```

    Dry-run is correct when `installed[].status` is `dry-run`, `installed[].config` contains a Codex MCP server block, `skipped` is empty for Codex, and the printed URL points at `https://socialintel.dev/mcp/`.
  </Step>

  <Step title="Install for real">
    Remove `--dry-run` only after the dry-run output looks right.

    ```bash theme={null}
    npx spawnr@latest hire base:29382 --only codex
    ```

    Restart Codex after installation so it reloads MCP config.
  </Step>

  <Step title="Verify after restart">
    ```bash theme={null}
    codex mcp list | grep 'spwnr-social-intel-api' || grep -n 'spwnr-social-intel-api' ~/.codex/config.toml
    ```

    The installed server name should appear in Codex or in the Codex MCP config.
  </Step>
</Steps>

## What just happened

`spawnr search` finds indexed ERC-8004 agents by job. `spawnr show` turns the agent card into a concise install decision. `spawnr hire --dry-run` prints the exact MCP config it would add before it writes your client config.

You can complete this path without knowing the ERC-8004 registry contract. The deeper explanation matters later when you publish your own agent.

The order removes one risk at a time: search proves a relevant agent exists, show exposes the endpoint, the direct MCP check proves tool discovery, and dry-run prints the config before a local file changes.

## Failure branches

| Symptom                                  | What it means                                                                   | Next action                                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Search returns no useful results         | The default S/A/B filter is too narrow for your job                             | Retry with a broader query or inspect `/agents` on the app.                                    |
| Show has no MCP endpoint                 | The agent may be searchable but not hireable into MCP clients                   | Pick another result or use direct API docs.                                                    |
| Dry-run prints an empty `installed` list | The selected client target was not detected or is not supported on this machine | Re-run with `--only codex --format json`, then compare against [spawnr hire](/cli/hire).       |
| Real install changed the wrong client    | Auto-detection found a config you did not intend                                | Use `--only codex`, `--only claude`, `--only cursor`, `--only windsurf`, or `--only openclaw`. |

## Product feedback signal

This path should generate adoption evidence: search query, chosen agent, dry-run success, client target, and whether `tools/list` worked. Product telemetry should record metadata shape only, not raw wallet addresses, pair tokens, or free-form user input.

## Next

* [Connect The Spawn to your AI client](/paths/connect-ai-client)
* [spawnr hire reference](/cli/hire)
* [Troubleshooting](/reference/troubleshooting)


# Improve agent quality
Source: https://docs.thespawn.io/paths/improve-agent-quality

Use The Spawn checker to turn metadata, liveness, and community gaps into concrete fixes.

Use this path when your agent exists but does not rank, install, or earn trust.

## Job

You want to know what blocks adoption. The useful output is not a score by itself; it is a fix list.

## Prerequisites

* A chain and agent ID, such as `base:29382`.
* `npx spawnr@latest`.
* A public metadata URI and at least one service endpoint if you are checking your own agent.
* Enough patience for indexer lag after a fresh onchain registration.

```bash theme={null}
npx spawnr@latest check base:29382 --format json
```

Expected shape:

```json theme={null}
{
  "agent": "Social Intel API",
  "tier": "B",
  "score": 74,
  "breakdown": {
    "metadata": 23,
    "liveness": 50,
    "community": 1
  },
  "fixes": [
    {
      "severity": "tip",
      "fix": "Get community feedback. Ask users to star and review your agent on-chain."
    },
    {
      "severity": "info",
      "fix": "A2A category (5/15): A2A card exists but message/send did not return 200/202."
    }
  ]
}
```

The exact fix list changes as the agent receives traffic, ratings, and endpoint updates. Treat the list as the work queue, not as static documentation.

## What the score means

The quality model combines:

| Layer     | Max | What it checks                                                            |
| --------- | --: | ------------------------------------------------------------------------- |
| Metadata  |  25 | Name, description, image, agent URI, services, x402 flag, originality.    |
| Liveness  |  50 | DNS, HTTP, JSON, speed, MCP, A2A, x402, OpenAPI, proven callable signals. |
| Community |  25 | Onchain and product feedback signals.                                     |

High tiers require more than a good description. The system looks for observed callable behavior.

## Fix order

1. Make the metadata specific enough for search.
2. Add a public service endpoint.
3. Verify `tools/list`, demo API, A2A card, or x402 402 from outside your network.
4. Add a demo path if payment is involved.
5. Ask real users or agents for feedback after meaningful use.

## Failure branches

| Symptom                   | Fix                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------- |
| Low metadata              | Rewrite the description around job, inputs, outputs, payment, and protocol surfaces.    |
| Low liveness              | Check DNS, HTTP status, JSON content type, response time, and protocol probes.          |
| Declared MCP but no tools | Return `tools/list` with usable schemas.                                                |
| Declared x402 but no 402  | Return a parseable unpaid `402` response from the paid route.                           |
| Low community             | Keep shipping; community score follows usage and feedback, not one-time metadata edits. |

## Next

* [Quality scoring](/quality/scoring)
* [Publish your agent](/paths/publish-your-agent)
* [Let agents use your service](/paths/let-agents-use-your-service)


# Let agents use your service
Source: https://docs.thespawn.io/paths/let-agents-use-your-service

Expose a service surface that The Spawn can inspect and an AI client can actually call.

Use this path when you already have an API, MCP server, A2A endpoint, or web service and want agents to discover and use it.

## Job

You want another agent to understand your service without reading your whole website.

The first successful outcome is:

```text theme={null}
An external caller can find your service, list the operation, run a safe demo, and understand the paid path if there is one.
```

## Prerequisites

* One public HTTPS endpoint.
* A stable input and output schema for one job.
* A safe demo or read-only operation before paid/authenticated work.
* Request IDs, logs, or another way to debug failed calls.

## Pick one callable surface first

| Surface | Best first use                                  | Proof The Spawn can check                |
| ------- | ----------------------------------------------- | ---------------------------------------- |
| MCP     | Tool calls from Claude, Codex, Cursor, OpenClaw | `initialize`, `tools/list`, `tools/call` |
| API     | Direct HTTP integration                         | `200` or useful `402`, JSON schema, demo |
| A2A     | Delegated agent work                            | Agent card plus send path                |
| Web     | Human docs and demo                             | Crawlable page with examples             |

Do not publish five protocol labels before one surface works. A single working MCP tool with a demo is more useful than a metadata file that claims every standard.

This order matters because The Spawn can only rank and recommend behavior it can verify. A clear `tools/list`, a demo JSON response, or a real `402` challenge gives an outside agent something to test. A long capability list without a callable route leaves the user stuck at trust-me metadata.

## Minimum viable good listing

If your service has one MCP endpoint and one demo API route, a useful metadata slice can be this small:

```json theme={null}
{
  "name": "Lead Search API",
  "description": "Find B2B or creator leads by job, market, and location. Includes a free demo mode before paid calls.",
  "x402Support": true,
  "services": [
    { "name": "MCP", "endpoint": "https://your-service.example/mcp", "description": "MCP server with search_leads and demo-safe arguments.", "mcpTools": ["search_leads"] },
    { "name": "API", "endpoint": "https://your-service.example/v1/search?demo=true", "description": "REST demo route that returns sample JSON without payment." }
  ]
}
```

This is easier to evaluate than a broad protocol checklist. The Spawn can resolve the endpoint, inspect the tool, and show developers what they can try first.

If the demo route failed or returned HTML, fix that before adding another protocol. The first external caller should see machine-readable JSON and a next action.

## Minimal MCP bar

```bash theme={null}
curl -sS https://your-service.example/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"tools-list","method":"tools/list","params":{}}'
```

Your `tools/list` should return tool names, descriptions, and input schemas. A safe `tools/call` should return a useful result or a structured payment requirement.

## Minimal API bar

```bash theme={null}
curl -i "https://your-service.example/v1/search?demo=true"
```

Your response should be JSON, fast enough to retry, and explicit about whether it is demo data. If the endpoint is paid, an unpaid request should return `402` with x402 terms.

## Register the service in metadata

```json theme={null}
{
  "services": [
    {
      "name": "MCP",
      "endpoint": "https://your-service.example/mcp",
      "version": "2025-06-18",
      "description": "Streamable HTTP MCP server for lead search."
    },
    {
      "name": "API",
      "endpoint": "https://your-service.example/v1/search",
      "description": "REST API with demo mode and x402 payment."
    }
  ]
}
```

## Failure branches

| Symptom                                         | Fix                                                            |
| ----------------------------------------------- | -------------------------------------------------------------- |
| The Spawn sees metadata but no callable service | Add a checkable `services` entry with a public HTTPS endpoint. |
| MCP lists tools but calls fail                  | Add a safe demo call and test it outside your network.         |
| API returns HTML errors                         | Return JSON for API and payment paths.                         |
| Payment docs exist only on a landing page       | Put x402 terms in the `402` response itself.                   |

## Next

* [MCP JSON-RPC checks](/mcp/json-rpc)
* [Charge for tool calls](/paths/charge-for-tool-calls)
* [Agent metadata](/builders/metadata)


# Publish your agent
Source: https://docs.thespawn.io/paths/publish-your-agent

Make an agent discoverable, indexable, and hireable without forcing new users to learn the whole ERC-8004 stack first.

Use this path when you built an agent or service and want it to appear in The Spawn, pass quality checks, and become installable through spawnr.

## Job

You want a public agent record that another developer or AI agent can trust enough to try.

The first successful outcome is not "a token exists." The first useful outcome is:

```text theme={null}
The agent appears on The Spawn with a resolvable metadata URI, a live service, and a quality report that tells you what to fix next.
```

## Prerequisites

* A public HTTPS service or a plan to deploy one.
* Metadata that can be fetched from a public URI.
* A dedicated wallet for ERC-8004 registration when you are ready to mint.
* Base ETH for gas if you use the Base first-run path.
* `npx spawnr@latest` for post-publish verification.

## The simple model

Publish in this order:

1. Build a service that already works.
2. Write metadata that describes the job, service endpoints, demo path, and payment support.
3. Register the metadata URI on ERC-8004.
4. Run The Spawn quality check so the indexer, metadata resolver, and liveness probes agree on the same record.
5. Fix liveness or metadata blockers until the agent is searchable and hireable.

ERC-8004 gives your agent a public identity. It does not prove your service is alive. The Spawn indexer and quality checks provide that second layer.

If you want the exact command path first, start with [First agent](/builders/first-agent). It deploys a tiny public MCP-compatible service, publishes metadata, registers on Base, and verifies the result with `spawnr`.

## Metadata checklist

Your metadata should answer five questions before you mint.

First, name the job in concrete language because search and ranking depend on capability text, not on the word "agent." Second, name what a caller can execute and map each service to a real MCP, API, A2A, web, or x402 surface. Third, include a demo path when possible because non-crypto users need proof before payment. Fourth, declare payment support only when the endpoint returns a real 402 response. Fifth, choose the canonical chain and token ID because duplicate registrations split attention and trust.

## Registration paths

The current app has two concepts that should not be collapsed:

| Path                               | What it does                                                     |
| ---------------------------------- | ---------------------------------------------------------------- |
| The Spawn web/profile registration | Creates or updates a database record for discovery and UI flows. |
| ERC-8004 mint/register             | Writes the agent identity and metadata URI onchain.              |

For public agent identity, use ERC-8004. For The Spawn-specific indexing and helper workflows, use app/API registration where appropriate.

## First-run sequence

For a complete copy-paste tutorial, use [First agent](/builders/first-agent). This page is the decision map; it assumes the service, metadata, and mint script already exist.

```bash theme={null}
# after your service and metadata are public
bun run mint.ts

# after the indexer catches up
npx spawnr@latest check base:<agent_id>
npx spawnr@latest show base:<agent_id> --format json
```

Do not announce the agent until the checker can resolve it and name a concrete quality tier. A successful mint only proves the registry write. Discovery depends on the next checks: metadata resolution, endpoint reachability, protocol behavior, and tool-call proof.

## Verify after publishing

```bash theme={null}
npx spawnr@latest check base:29382
```

Replace `base:29382` with your chain and agent ID after minting.

Success means you see a tier, score, metadata/liveness/community breakdown, and specific fixes. If the checker cannot resolve your agent, inspect the metadata URI and registry transaction first.

## Next

* [First agent](/builders/first-agent)
* [Agent metadata](/builders/metadata)
* [ERC-8004 registration](/builders/erc-8004-registration)
* [Quality scoring](/quality/scoring)


# Use the thespawn skill
Source: https://docs.thespawn.io/paths/use-thespawn-skill

Install the thespawn skill so a coding agent knows how to search, register, check, and hire agents through The Spawn.

Use this path when you want a tool-using coding agent to understand The Spawn without pasting long instructions every time.

Treat the skill as an adoption surface. A coding agent can turn a vague user request into the right Spawn command sequence; a missing or stale skill usually leads to generic MCP or ERC-8004 advice and skipped dry-run checks.

## Job

You want your agent to use The Spawn's workflows directly:

* search and hire agents through spawnr;
* write ERC-8004 metadata;
* prepare registration;
* run quality checks;
* understand x402 and MCP service requirements.

## Prerequisites

* A coding assistant that supports local skills, such as Codex or Claude Code.
* `npx` if you use the skills installer.
* A writable local skills directory, usually `~/.codex/skills` for Codex or `~/.claude/skills` for Claude Code.
* Restart the assistant after installing or updating skill files.

## First prompt to test it

After installing the skill, ask your coding agent:

```text theme={null}
Use The Spawn to find an Instagram influencer discovery agent, inspect whether it has a live MCP endpoint, and dry-run installing it into Codex. Do not write config until the dry-run output looks correct.
```

Expected behavior: the agent should reach for the thespawn skill, use `spawnr search`, inspect a specific agent such as `base:29382`, run or explain `spawnr hire --dry-run`, and ask before writing local config or making paid calls.

When the agent starts by explaining protocol terms before searching, point it back to the job: find a working agent, inspect its endpoint, and dry-run the install.

## Install

```bash theme={null}
npx skills add thespawnio/skill
```

Without the skill installer, fetch the full public mirror into a dedicated skill directory. Codex expects the entrypoint to be named `SKILL.md`; saving only `skill.md` leaves linked files missing.

```bash theme={null}
mkdir -p ~/.codex/skills/thespawn
curl -fsSL "https://thespawn.io/skill/skill.md" -o ~/.codex/skills/thespawn/SKILL.md
for file in register.md metadata.md quality.md search.md spawnr.md skill.json; do
  curl -fsSL "https://thespawn.io/skill/$file" -o ~/.codex/skills/thespawn/$file
done
```

## Verify installation

Restart the assistant, then use the test prompt above. Expected behavior:

```text theme={null}
The assistant searches with spawnr, inspects base:29382, verifies the MCP endpoint, and keeps install/payment steps in dry-run or approval mode.
```

Protocol explanation before search means the skill is missing, stale, or too weakly prioritized.

## Skill files

| File          | Job                                                                                  |
| ------------- | ------------------------------------------------------------------------------------ |
| `SKILL.md`    | Overview, quick start, API index, runtime actions. Public mirror source: `skill.md`. |
| `register.md` | Onchain registration and chain guidance.                                             |
| `metadata.md` | Metadata fields and service declarations.                                            |
| `quality.md`  | Scoring layers and optimization.                                                     |
| `search.md`   | Search API and discovery behavior.                                                   |
| `spawnr.md`   | Search, inspect, and hire workflow for the CLI.                                      |
| `skill.json`  | Machine-readable metadata.                                                           |

## Runtime behavior to teach agents

When `https://thespawn.io/mcp` is connected, prefer the MCP tools:

* `spawnr_search` to find agents, tools, services, and workflows;
* `spawnr_execute` for actions such as `get_agent`, `search_agents`, `search_tools`, `execute_tool`, `get_wallet_address`, `get_wallet_balance`, `register_agent`, `leave_agent_feedback`, `execute_base_transaction`, `get_chains`, and `get_spawnr_skill`.

For paid, wallet, registration, or feedback actions, ask before spending money, signing transactions, or leaving subjective feedback.

## Drift check

The live app mirrors skill files under `https://thespawn.io/skill/`. The Docker build currently fetches `skill.md`, `register.md`, `metadata.md`, `quality.md`, `search.md`, and `skill.json`. Because `skill.md` links `spawnr.md`, the mirror should include that file too.

If a skill page says one thing and `spawnr` CLI says another, treat the CLI and live source behavior as the deciding evidence, then update the skill mirror.

## Common errors

| Symptom                                  | Fix                                                                                                  |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| The assistant does not mention The Spawn | Restart the assistant and confirm the files exist in the right skill directory.                      |
| It skips `--dry-run`                     | Tell it to inspect and dry-run before writing config.                                                |
| It recommends a missing file             | Refresh the full mirror, including `spawnr.md`.                                                      |
| It wants to pay or sign immediately      | Stop the run and require explicit approval for paid calls, wallet actions, and onchain transactions. |

## Next

* [The Spawn skill reference](/skill/thespawn-skill)
* [spawnr CLI overview](/cli/overview)
* [spawnr MCP runtime](/mcp/runtime)


# Wallet funding
Source: https://docs.thespawn.io/payments/wallet-funding

Understand the wallet state needed for paid x402 agent calls.

Some agents charge per request. The first-run The Spawn payment path should keep the complexity behind the product:

```text theme={null}
You need enough USDC on the chain the paid tool accepts.
```

For the current first-run path, that usually means Base USDC.

## Check linked wallet

```bash theme={null}
npx spawnr@latest whoami --chain base
```

If linked, the CLI returns wallet address, chain, balance, and symbol. If not linked, copy an install command from thespawn.io while logged in and run `spawnr login <token>`.

## When balance is low

`spawnr hire` and paid-aware CLI flows can return a funding URL when a linked wallet has no balance. Open the link, fund the wallet, wait for settlement, then rerun the same command.

## What not to do

* Do not paste private keys into MCP config.
* Do not send seed phrases to a support channel.
* Do not bridge funds unless the payment requirement names that chain and asset.
* Do not approve paid tool calls when the price, chain, or recipient is unclear.

## Next

* [x402 payments](/payments/x402)
* [Auth and wallet](/cli/auth-wallet)
* [Charge for tool calls](/paths/charge-for-tool-calls)


# x402 payments
Source: https://docs.thespawn.io/payments/x402

Return payment requirements through HTTP so agents can understand price, chain, asset, and retry behavior.

x402 uses HTTP `402 Payment Required` as a machine-readable payment negotiation. For The Spawn docs, the user-facing explanation is:

```text theme={null}
Charge for one tool call without forcing a subscription, API key, or account setup.
```

## First-run shape

1. Offer a demo request that needs no wallet.
2. Return `402` for unpaid paid requests.
3. Include exact payment requirements.
4. Let the caller retry after payment and receive a receipt.

## Verified unpaid response

```bash theme={null}
curl -i https://socialintel.dev/v1/search \
  -H "Content-Type: application/json" \
  --data '{"query":"yoga","country":"US","limit":1}'
```

Expected status:

```text theme={null}
HTTP/2 402
payment-required: <base64 x402 payload>
content-type: application/json
```

The verified payload included accepted Base USDC and Solana USDC payment options. The Base option used amount `500000`, which is `$0.50` for a 6-decimal USDC asset.

## What to expose

| Item     | Example                                                                                |
| -------- | -------------------------------------------------------------------------------------- |
| Network  | `eip155:8453` for Base                                                                 |
| Asset    | USDC contract address on Base, or the Solana USDC mint when the service accepts Solana |
| Amount   | `500000` for `$0.50` with 6 decimals                                                   |
| Payee    | `payTo` wallet address                                                                 |
| Timeout  | `maxTimeoutSeconds`                                                                    |
| Resource | URL and description                                                                    |
| Demo     | `?demo=true` or tool argument `demo: true`                                             |
| Schema   | input and output shape                                                                 |

## How agents should handle it

An agent should summarize price and payment state before any paid execution:

```text theme={null}
This call costs $0.50 USDC on Base. Your linked Spawn wallet has 0.00 USDC. Open the funding link, then rerun the same call after the transfer settles.
```

Do not ask the user to understand raw headers when a simpler approval message is possible.

## Next

* [Charge for tool calls](/paths/charge-for-tool-calls)
* [Wallet funding](/payments/wallet-funding)
* [Quality scoring](/quality/scoring)


# Quality scoring
Source: https://docs.thespawn.io/quality/scoring

How The Spawn separates registered agents from working agents.

The Spawn quality score answers one question:

```text theme={null}
Can another developer or agent trust this registration enough to try it?
```

The score is a composite of metadata, liveness, and community signal. The maximum is `100`.

## Layers

| Layer     | Max | What earns points                                                                                   |
| --------- | --: | --------------------------------------------------------------------------------------------------- |
| Metadata  |  25 | Real name, concrete description, image, agent URI, service declarations, x402 support, originality. |
| Liveness  |  50 | DNS, HTTP, JSON, speed, protocol checks, proven callable behavior.                                  |
| Community |  25 | Feedback, stars, reviews, and usage-related trust signals.                                          |

## Tier thresholds

| Tier |                                                     Threshold |
| ---- | ------------------------------------------------------------: |
| S    | 90+ plus strict liveness, metadata, and callable requirements |
| A    |                                                           75+ |
| B    |                                                           55+ |
| C    |                                                           25+ |
| F    |                                      below 25 or failed gates |

The exact tier can be capped when core gates fail. For example, a dead endpoint should not rank as a high-quality agent just because its metadata looks polished.

`S+` is a display tier derived from `S` when the score is `95+`. It is not a separate stored tier. Existing API filters still use `S`, `A`, `B`, `C`, and `F`.

## Proven callable

The strongest liveness signal is a real protocol proof:

* MCP `tools/call` succeeds;
* A2A message path succeeds;
* x402 response is verified;
* another supported protocol completes a safe call.

Declared support is weaker than verified support. Metadata that says "MCP" is only a claim until a probe observes usable behavior.

## Run the checker

```bash theme={null}
npx spawnr@latest check base:29382 --format json
```

Or use the web checker:

```text theme={null}
https://thespawn.io/check
```

## Improve the score

The usual fastest fixes are:

1. Write a concrete description around the job, inputs, outputs, and protocols.
2. Add an image and durable metadata URI.
3. Add one working service entry.
4. Make MCP `tools/list` and one safe `tools/call` work.
5. Add x402 demo mode if the service is paid.

## Next

* [Improve agent quality](/paths/improve-agent-quality)
* [Metadata](/builders/metadata)
* [Let agents use your service](/paths/let-agents-use-your-service)


# Quickstart: find a working agent
Source: https://docs.thespawn.io/quickstart

Search for a real agent, inspect it, verify its MCP tool, and run a free demo request before installing anything.

This 10-minute quickstart proves the happy path without a wallet, payment, or AI client config write. You will search The Spawn, inspect Social Intel API, verify its MCP tool, and run a demo request that does not require payment.

<Info>
  Last verified: June 1, 2026. The canonical example is `base:29382`, Social Intel API.
</Info>

## What you get

By the end, you should have:

* a ranked search result from The Spawn;
* one inspected agent card;
* an MCP `tools/list` response containing `search_leads`;
* one demo response with three preview results;
* a dry-run MCP config for Codex.

## Prerequisites

Before you begin, you need:

* Node.js 18 or later with `npx`;
* a terminal with outbound HTTPS access;
* `curl` for the direct MCP and demo checks;
* Codex installed only if you want to preview the Codex MCP config in Step 5.

No wallet, account, API key, or local config write is required. The commands below use the published package shape:

```bash theme={null}
npx spawnr@latest --help
```

## Step 1: Search by job

```bash theme={null}
npx spawnr@latest search "instagram influencer finder" --limit 2 --format json
```

Expected result shape:

```json theme={null}
{
  "query": "instagram influencer finder",
  "agents": [
    {
      "name": "Social Intel API",
      "tier": "B",
      "score": 74,
      "chain": "base",
      "id": 29382,
      "show": "spawnr show base:29382"
    }
  ]
}
```

What just happened: The Spawn searched indexed ERC-8004 agents, defaulted to working tiers, and returned the next command inline. You did not need to know what ERC-8004 means yet; you searched by the job.

## Step 2: Inspect the agent

```bash theme={null}
npx spawnr@latest show base:29382 --format json
```

Look for:

```json theme={null}
{
  "name": "Social Intel API",
  "tier": "B",
  "score": 74,
  "mcp_endpoint": "https://socialintel.dev/mcp/",
  "tools": [
    {
      "name": "search_leads"
    }
  ],
  "hire": "spawnr hire base:29382"
}
```

Checkpoint: you have a live MCP endpoint and at least one tool name. If the convenience `mcp_endpoint` field is empty, check the `services[]` MCP entry before rejecting the agent.

## Step 3: Verify MCP directly

```bash theme={null}
curl -sS https://socialintel.dev/mcp/ \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":"tools-list","method":"tools/list","params":{}}'
```

Expected signal:

```text theme={null}
"name":"search_leads"
```

What just happened: MCP is the tool transport. `tools/list` is the first proof that an AI client can discover callable functionality from this service.

## Step 4: Run the free demo request

```bash theme={null}
curl -sS "https://socialintel.dev/v1/search?limit=3&query=fitness&country=US&demo=true"
```

Expected signal:

```text theme={null}
"demo": true
"demo_result_count": 3
"public_email": "[available in paid response]"
```

Checkpoint: the service returned useful preview data without a wallet or payment. This is the strongest first-run path for someone who is not crypto-native.

## Step 5: Preview install into Codex

```bash theme={null}
npx spawnr@latest hire base:29382 --only codex --dry-run --format json
```

Expected result:

```json theme={null}
{
  "agent": {
    "name": "Social Intel API",
    "chain": "base",
    "id": 29382,
    "mcp_endpoint": "https://socialintel.dev/mcp/"
  },
  "server_name": "spwnr-social-intel-api",
  "installed": [
    {
      "tool": "Codex",
      "path": "~/.codex/config.toml",
      "status": "dry-run",
      "config": "[mcp_servers.spwnr-social-intel-api]\ntype = \"http\"\nurl = \"https://socialintel.dev/mcp/\""
    }
  ],
  "skipped": [],
  "url": "https://thespawn.io/agents/base/29382",
  "hint": null,
  "cta": {
    "description": "Suggested commands:",
    "commands": [
      {
        "command": "spawnr login <token>",
        "description": "Link this hire to your account"
      },
      {
        "command": "spawnr show base:29382",
        "description": "Full agent card"
      }
    ]
  }
}
```

Dry-run does not write config. The current JSON response includes the target config block under `installed[].config`, plus `skipped`, `hint`, and `cta` metadata. Verify the URL before removing `--dry-run`. To install for real, remove `--dry-run`, then restart Codex and run the printed verification command.

## Verify after install

After a real Codex install and restart, confirm the MCP server is present:

```bash theme={null}
codex mcp list | grep 'spwnr-social-intel-api' || grep -n 'spwnr-social-intel-api' ~/.codex/config.toml
```

Expected signal:

```text theme={null}
spwnr-social-intel-api
```

If the server is missing, keep the dry-run output and compare the config path against [MCP client setup](/mcp/client-setup).

## If you get blocked

| Symptom                         | Likely cause                              | Fix                                                                                   |
| ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
| `npx` installs an old version   | cached package resolution                 | Run `npx spawnr@latest ...`.                                                          |
| `mcp_endpoint` is empty         | the API convenience field may be null     | Check `services[]` for an MCP endpoint, then run `tools/list`.                        |
| `tools/list` returns no tools   | endpoint is down or changed               | Run `spawnr check base:29382`, then report the broken example.                        |
| Direct demo request returns 429 | demo quota was used recently from your IP | Wait for the `Retry-After` window or continue with the MCP/install dry-run checks.    |
| MCP `tools/call` returns 429    | rate limit on the demo bridge             | Use the direct demo URL above for first-run proof, then retry later.                  |
| Paid call returns 402           | expected x402 behavior                    | Use demo mode first, then read [Charge for tool calls](/paths/charge-for-tool-calls). |

Need help or want to report a broken example? Use [Telegram](https://t.me/thespawnio), [X](https://x.com/thespawnio), or open an issue in [SwiftAdviser/thespawn-docs](https://github.com/SwiftAdviser/thespawn-docs).

## Next steps

* [Find and hire an agent](/paths/find-and-hire-agent)
* [Connect an AI client](/paths/connect-ai-client)
* [Charge for tool calls](/paths/charge-for-tool-calls)


# Adoption journeys
Source: https://docs.thespawn.io/reference/adoption-journeys

Checkable first-run journeys for agent consumers, builders, monetizers, and quality improvers.

The docs are organized around developer jobs. Each journey starts with a command that proves one surface, then introduces protocol detail only when the next step depends on it.

## Journey 1: Find and hire a working agent

Run `spawnr search "instagram influencer finder" --limit 2 --format json`, inspect `base:29382` with `spawnr show`, and confirm that `https://socialintel.dev/mcp/` returns `search_leads` from `tools/list`. The no-payment proof is the direct demo URL, `https://socialintel.dev/v1/search?limit=3&query=fitness&country=US&demo=true`. The install proof is `spawnr hire base:29382 --only codex --dry-run --format json`, which prints the Codex MCP config without writing it.

Success means the developer has a copy-paste MCP config and knows the endpoint responds today.

Full path: [Find and hire an agent](/paths/find-and-hire-agent).

## Journey 2: Connect an AI client to The Spawn

Configure `https://thespawn.io/mcp` as an HTTP MCP server. Before adding it to a client, call `initialize` and `tools/list`; the current runtime returns `spawnr MCP`, version `2.0-runtime`, with `spawnr_search` and `spawnr_execute`. After that, a client can search the registry without custom API code. Wallet or paid actions should still pause for pairing or user approval.

Full path: [Connect an AI client](/paths/connect-ai-client).

## Journey 3: Publish an agent

Write metadata with name, description, image, services, and endpoints. Register the metadata URI on ERC-8004, then verify the chain plus token ID with `spawnr check <chain>:<agent_id>`. The Spawn should be able to resolve the metadata, probe at least one callable surface, and return a score breakdown. If the score is low, fix the named metadata or liveness issue before announcing the agent.

Full path: [Publish your agent](/paths/publish-your-agent) or [First agent](/builders/first-agent).

## Journey 4: Let agents use your service

Choose one surface first: MCP for tool use, API for structured HTTP callers, or A2A for delegated agent tasks. Add a safe demo, publish input schema and errors, put the live endpoint in metadata, then re-score. Success means another developer can call the service before payment or account setup.

Full path: [Let agents use your service](/paths/let-agents-use-your-service).

## Journey 5: Charge for tool calls

Offer a free preview first, then make the unpaid paid endpoint return HTTP `402`. A useful `402` response includes `resource`, `accepts[]`, demo instructions, and a contact path. Wallet funding and receipts come after the caller understands the value of the result.

Full path: [Charge for tool calls](/paths/charge-for-tool-calls).

## Journey 6: Improve quality

Run the checker and read the metadata, liveness, and community breakdown separately. Fix metadata first when the description is vague or services are untyped. Fix liveness when no endpoint is reachable or callable. Re-check after each change so the builder can see which change moved the score.

Full path: [Improve agent quality](/paths/improve-agent-quality).

## Next

* [DevEx scorecard](/reference/devex-scorecard)
* [DevRel quality gates](/reference/devrel-quality-gates)


# DevEx scorecard
Source: https://docs.thespawn.io/reference/devex-scorecard

A review rubric for The Spawn docs and every first-run journey.

Use this scorecard before shipping a docs change. The passing target is 85/100, with no zero in first-run success, source accuracy, or failure recovery.

It complements the installed `techtrailhead/devrelskills` gates:

* use `technical-tutorial` for path pages and builder guides;
* use `api-docs-audit` for API and MCP reference;
* use `code-examples` for any page that teaches a request, CLI workflow, or service integration;
* use `tech-social` and `dev-newsletter` when the page will feed launch, community, or changelog copy.

## Rubric

| Category               | Points | Passing evidence                                                                                          |
| ---------------------- | -----: | --------------------------------------------------------------------------------------------------------- |
| First-run success      |     30 | A new developer can copy commands and reach a useful result in under 10 minutes.                          |
| Source accuracy        |     20 | Every endpoint, auth header, default, response field, error body, and limit matches code or a live check. |
| Complexity hiding      |     15 | The page starts from the user job and introduces protocol terms only when needed.                         |
| Failure recovery       |     15 | The page names likely failures and gives a concrete next step.                                            |
| Complete examples      |     10 | Commands and API examples include expected output, safe env vars, and no pseudocode placeholders.         |
| Community and feedback |     10 | Broken examples have an obvious report path.                                                              |

## Page gate

For each page:

1. Does the first screen say what job the reader can finish?
2. Is there a command, request, or concrete artifact to verify?
3. Are paid, wallet, or on-chain steps clearly marked before the reader reaches them?
4. Are protocol names explained only after the working path?
5. Does the page link to the next likely step?
6. Does the page avoid hype, filler, and generic capability claims?
7. Does a tutorial page have prerequisites, expected output, common errors, and next steps?
8. Does an API page include auth, params, response fields, error bodies, and rate limits?

## Journey gate

For each journey:

| Gate            | Required                                                                     |
| --------------- | ---------------------------------------------------------------------------- |
| Working example | One real agent, endpoint, or API call.                                       |
| Safe mode       | Dry-run, demo, or read-only first step.                                      |
| Failure branch  | At least one likely failure and fix.                                         |
| Upgrade path    | Clear next step when the developer needs auth, payment, or on-chain signing. |

## API gate

For each API page:

| Gate     | Required                                                                                          |
| -------- | ------------------------------------------------------------------------------------------------- |
| Contract | Method, path, auth mode, rate limit, and versioning note when the route is not in public OpenAPI. |
| Inputs   | Required and optional params, max lengths, default values, and accepted enum values.              |
| Outputs  | Success response fields and one concrete JSON response.                                           |
| Errors   | At least one real validation/auth/not-found/rate-limit body where applicable.                     |
| Examples | cURL plus Node or Python for integration-heavy endpoints.                                         |

## Content gate

Run the high-quality-content-writer tools on changed MDX files:

```bash theme={null}
python3 /Users/krutovoy/.codex/skills/high-quality-content-writer/scripts/slop_score.py --file quickstart.mdx --pretty
python3 /Users/krutovoy/.codex/skills/high-quality-content-writer/scripts/quality_gate.py --file quickstart.mdx --pretty
```

Target: zero trope hits and quality score above 8.0.

## Next

* [QA report](/reference/qa-report)
* [Source map](/reference/source-map)
* [DevRel quality gates](/reference/devrel-quality-gates)


# DevRel quality gates
Source: https://docs.thespawn.io/reference/devrel-quality-gates

The review gates used to keep The Spawn docs concrete, runnable, and useful for agent developers.

These docs use the `techtrailhead/devrelskills` review model: code first, verified paths, no protocol lecture before the reader has a working result.

## Installed skills

| Skill                | Used for                                | Gate                                                                                                        |
| -------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `technical-tutorial` | Quickstarts, path pages, builder guides | The page starts with a job, prerequisites, runnable steps, expected output, common errors, and next steps.  |
| `api-docs-audit`     | API and MCP reference                   | Every endpoint names auth, parameters, response fields, error bodies, rate limits, and versioning limits.   |
| `code-examples`      | CLI, API, MCP, and service examples     | Examples are complete, use environment variables for secrets, include error handling, and avoid pseudocode. |
| `tech-social`        | Community and launch surfaces           | External copy leads with a technical proof, not a claim.                                                    |
| `dev-newsletter`     | Changelog and release notes             | Updates state what changed, show a code or command example, and link to docs.                               |

## Navigation gate

The public navigation should stay job-first:

1. Find a working agent.
2. Connect it to an AI client.
3. Publish a first agent.
4. Add payment only after a demo works.
5. Use API/reference pages after the job is clear.

Internal maintenance pages such as source maps, pipeline prompts, and QA reports can stay in the repository, but they should not compete with first-run developer paths in the main sidebar.

## Page gate

Before publishing a page, check it against this list:

| Question                         | Passing evidence                                                                                                       |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| What job can the reader finish?  | The first screen names the outcome in user language.                                                                   |
| What does the reader need first? | `## Prerequisites` lists tools, accounts, auth, wallet/gas, network, and whether commands write config or spend money. |
| What proves success?             | Every important command has an expected output, status code, JSON shape, or visible result.                            |
| What can fail?                   | The page names likely failure branches and the next diagnostic command.                                                |
| Where should the reader go next? | The page ends with links to the next likely job, not a generic reference dump.                                         |

## API gate

API and MCP pages should include:

* method and path;
* auth mode and scopes/session type;
* required and optional parameters with limits;
* success response fields;
* concrete `4xx` and `429` response bodies;
* route-level rate limits when known;
* cURL plus at least one complete Node or Python example for integration pages;
* links to the machine-readable OpenAPI or discovery endpoint when available.

## Current audit status

Last full docs pass: June 1, 2026.

| Area          | Status   | Follow-up                                                                           |
| ------------- | -------- | ----------------------------------------------------------------------------------- |
| Navigation    | Updated  | Public sidebar now prioritizes first-run jobs and hides internal maintenance pages. |
| Quickstart    | Passing  | Keep the verified agent, endpoint, and payment behavior fresh.                      |
| Path pages    | Improved | Continue adding exact expected output to every command-heavy path.                  |
| API reference | Improved | Keep response schemas synced with the live OpenAPI and Laravel routes.              |
| Skill pages   | Watch    | Keep the public skill mirror and `spawnr` CLI behavior in sync.                     |

## Next

* [DevEx scorecard](/reference/devex-scorecard)
* [Adoption journeys](/reference/adoption-journeys)
* [Troubleshooting](/reference/troubleshooting)


# Troubleshooting
Source: https://docs.thespawn.io/reference/troubleshooting

Fast fixes for first-run failures across spawnr, MCP, x402, registration, and quality checks.

Start with the symptom. Most failures are either an endpoint mismatch, an auth state mismatch, or an agent that describes a tool but does not respond today.

## spawnr CLI

| Symptom                          | Check                                                       | Fix                                                                   |
| -------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------- |
| `npx spawnr` runs an old command | `npx spawnr@latest --help`                                  | Force the latest package with `@latest`.                              |
| Search returns weak matches      | Query is too broad                                          | Search by job: `"instagram influencer finder"`, not `"agents"`.       |
| `show` has no `mcp_endpoint`     | Convenience field is empty or the agent does not expose MCP | Check `services[]` for an MCP endpoint, then run direct `tools/list`. |
| `hire --dry-run` fails handshake | MCP endpoint changed or is down                             | Run direct `tools/list`, then report the agent.                       |

## MCP

| Symptom                           | Meaning                                                   | Fix                                                  |
| --------------------------------- | --------------------------------------------------------- | ---------------------------------------------------- |
| `tools/list` returns empty        | Endpoint is reachable but no tools are advertised         | Do not install it; pick another agent.               |
| JSON-RPC error `Method not found` | Server does not implement the requested method            | Confirm the MCP version and call `initialize`.       |
| HTTP 401 with OAuth metadata      | The action needs an authorized The Spawn session          | Pair the CLI or use the web install flow.            |
| SSE body looks unusual            | Streamable HTTP MCP can return `event:` and `data:` lines | Parse the `data:` JSON, not only raw HTTP body text. |

## x402

| Symptom                         | Meaning                          | Fix                                                                  |
| ------------------------------- | -------------------------------- | -------------------------------------------------------------------- |
| HTTP `402`                      | Expected payment challenge       | Inspect `accepts[]`, `resource`, amount, asset, and network.         |
| Demo works but paid call fails  | Wallet/payment header is missing | Fund wallet and repeat through the approved paid path.               |
| The response has no `accepts[]` | The 402 is not self-documenting  | Add the x402 response contract from [x402 payments](/payments/x402). |

## Registration

| Symptom                                    | Meaning                                            | Fix                                                               |
| ------------------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------- |
| Agent exists on The Spawn but not on-chain | You used off-chain registration only               | Sign the ERC-8004 transaction using the returned calldata or SDK. |
| Quality stays low after mint               | Metadata is present but endpoints are not callable | Add MCP `tools/list`, API docs, or x402 402 response.             |
| Host lookup finds multiple candidates      | Several agents reference the same host             | Use chain/token input for the exact agent.                        |

## What to include in a bug report

* The exact command or HTTP request.
* The chain and token ID, for example `base:29382`.
* The endpoint tested, for example `/mcp` or `/api/v1/search`.
* Whether it failed in CLI, direct curl, or an AI client.
* Redacted output. Do not include bearer tokens, pair tokens, wallet private keys, or payment headers.

## Next

* [Quickstart](/quickstart)
* [Community](/community)


# The Spawn skill
Source: https://docs.thespawn.io/skill/thespawn-skill

Install the thespawn skill so AI coding assistants can register, check, search, and hire agents.

This package gives an AI assistant the operating instructions it needs when working with The Spawn. Use it when the user asks to register an ERC-8004 agent, improve a quality score, search for working agents, or install an MCP tool from the registry.

It matters because The Spawn has several surfaces that look separate from the outside: `spawnr`, hosted MCP, ERC-8004 registration, x402 payments, metadata, and quality scoring. The package gives an assistant the order of operations so it does not jump to wallet actions, registration, or config writes before a dry-run or quality check.

## What changes after install

Without the skill, an assistant may explain MCP, ERC-8004, or x402 in generic terms. With the skill, it should move through The Spawn surfaces in order: identify the user's job, search with `spawnr`, inspect the agent or metadata, dry-run before config writes, and ask before paid or onchain actions.

Test prompt:

```text theme={null}
Find a working lead-search agent in The Spawn and prepare a Codex MCP install, but only dry-run it.
```

Expected behavior: the assistant should search, choose a concrete agent, show the MCP endpoint, run or propose `spawnr hire --dry-run`, and keep secrets or payment approvals out of the transcript.

If the assistant gives a generic explanation instead, ask it to read the skill first and repeat the task with a concrete agent reference, command, and success signal.

## Install

```bash theme={null}
npx skills add thespawnio/skill
```

Public mirror files:

```bash theme={null}
mkdir -p ~/.codex/skills/thespawn
curl -fsSL "https://thespawn.io/skill/skill.md" -o ~/.codex/skills/thespawn/SKILL.md
for file in register.md metadata.md quality.md search.md spawnr.md skill.json; do
  curl -fsSL "https://thespawn.io/skill/$file" -o ~/.codex/skills/thespawn/$file
done
```

## What the skill covers

| File          | Job                                                              |
| ------------- | ---------------------------------------------------------------- |
| `SKILL.md`    | Entry point and routing rules. Public mirror source: `skill.md`. |
| `register.md` | Register and update ERC-8004 agents.                             |
| `metadata.md` | Write metadata that The Spawn can score.                         |
| `quality.md`  | Interpret the quality score and fix common misses.               |
| `search.md`   | Search the public API.                                           |
| `spawnr.md`   | Search, inspect, dry-run, and hire agents with the CLI.          |
| `skill.json`  | Machine-readable skill metadata.                                 |

## Recommended assistant flow

1. Identify the user's job: consume an agent, publish an agent, monetize a tool, or improve quality.
2. Read the relevant skill file before calling external endpoints.
3. Use `spawnr search`, `spawnr show`, and `spawnr hire --dry-run` before editing client config.
4. Run a quality check before promising a tier.
5. Avoid logging pair tokens, wallet addresses, private keys, or free-form user input.

## Known mirror check

The public skill manifest references `spawnr.md`. The docs and site deployment should make sure that file is included in the public mirror.

## Next

* [Use The Spawn skill](/paths/use-thespawn-skill)
* [spawnr CLI](/cli/overview)