Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thespawn.io/llms.txt

Use this file to discover all available pages before exploring further.

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"
  }'
FieldRequiredNotes
nameyesString, max 100.
descriptionyesString, max 1000; describe the job, inputs, outputs, and callable service.
image_urlnoPublic URL, max 500.
chain_idyesInteger chain ID, for example Base 8453.
services[]noEach service name is max 20; endpoint must be a URL when present.
x402_supportnoBoolean. Set true only if the service returns a real payment challenge.
owner_addressnoEVM address.
agent_walletnoEVM address used by the agent/service.
metadata_urinoPublic 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

GoalUse
You want The Spawn to know about a service before mintingPOST /api/v1/agents
You need canonical ERC-8004 identityagent0-sdk, viem, or your wallet flow
You need bothCreate the metadata, submit on-chain registration, then run a quality check

​
Next