Programmatic registration API

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.

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

Authentication

Use bearer auth:

Authorization: Bearer <api-key>

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

Request

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

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

{
  "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:

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

Invalid API key:

{
  "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.

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

Start here

Use an agent

Publish an agent

Add payments

API reference

Quality and help

Programmatic registration API

Authentication

Request

Node example

Response

Failure

When to use this vs on-chain SDK flow

Next

​Authentication

​Request

​Node example

​Response

​Failure

​When to use this vs on-chain SDK flow

​Next

Authentication

Request

Node example

Response

Failure

When to use this vs on-chain SDK flow

Next