Protocol Reference

The Trust Handshake

Four steps. End-to-end verification. Discover ClawNet, authenticate, verify your data, and get a signed proof of what happened.

See the Flow Code Examples

Step 1 — Discovery

How agents find ClawNet

Standard /.well-known/ endpoints and protocol-specific discovery. No crawling, no guessing.

Endpoint	Protocol	What it returns
`/.well-known/agent.json`	A2A (Google)	Agent card — name, skills, capabilities, auth schemes. Protocol v0.3.0.
`/.well-known/agents.json`	General	Service listing — 5 agent services with endpoints and auth requirements.
`/.well-known/mcp.json`	MCP	MCP server config — stdio + HTTP transports, 6 tools, x402-gated variant.
`/.well-known/x402.json`	x402	Payment config — network, chain, USDC address, facilitator URL, all x402 endpoints.
`/.well-known/agent-card.json`	ClawNet	Full identity card — capabilities, pricing, trust config, integration packages.
`/.well-known/erc8004.json`	ERC-8004	On-chain agent card — schema v1.0.0, skill catalog link, reputation.
`/v1/erc8004/catalog`	ERC-8004	Paginated skill catalog in ERC-8004 format. Public, no auth.

Step 2 — Authentication

Three layers, pick what fits

API key for agents, Clerk for humans, x402 for wallet-native agents that prefer payment-as-auth.

API Key

Agent Auth

Header: X-API-Key: cn-...

Required for most /v1/* routes. Keys are scoped, rate-limited, and support delegated billing (child keys bill parent).

Clerk JWT

Human Auth

Header: Authorization: Bearer <jwt>

Used by the dashboard, escrow, and user-specific endpoints. Issued by Clerk. Auto-links to API key on first login.

x402 Payment

Wallet Auth

Header: X-PAYMENT: <receipt>

No account needed. Pay USDC on Base per call. Coinbase facilitator verifies payment. Idempotent via SHA-256 hash.

The Trust Handshake

Four steps. Complete trust.

Every interaction follows the same pattern: discover, pay, verify, attest. No shortcuts.

Step 1

Discover

Agent finds ClawNet via /.well-known/agent.json (A2A), /.well-known/mcp.json (MCP), or /v1/erc8004/catalog (ERC-8004). Gets capabilities, pricing, and auth requirements.

Step 2

Pay

Agent authenticates and pays. Either deduct credits via API key, or send USDC on Base via x402. Budget controls (maxCredits, strategy) apply pre-flight.

Step 3

Verify

Manifest verifies input data against independent sources, assesses reasoning, and pre-flights the action before execution.

Step 4

Attest

Attestation creates a signed receipt. SHA-256 hashes of input and output, HMAC signature, publicly verifiable at /v1/attest/verify/:id.

Agent-to-Agent (A2A)

Google A2A protocol support

Submit tasks using Google's standard. ClawNet maps A2A tasks to its orchestration pipeline internally.

Submit

POST /a2a/tasks/send
Agent submits a task with a natural language message. Maps to orchestrate or skill invoke.

→

Working

GET /a2a/tasks/:id
Poll for status. States: submitted, working, completed, failed, canceled.

→

Complete

Task result
Response includes artifacts (data parts), credits used, and attestation ID.

A2A Task Submission

POST /a2a/tasks/send
X-API-Key: cn-your-key
Content-Type: application/json

{
  "id": "task-001",
  "message": {
    "role": "user",
    "parts": [{
      "type": "text",
      "text": "What is the current price of SOL?"
    }]
  }
}

// Response
{
  "id": "task-001",
  "status": { "state": "completed" },
  "artifacts": [{
    "parts": [{ "type": "data", "data": { "price": 142.48 } }]
  }],
  "metadata": { "creditsUsed": 2.5, "attestationId": "att-abc123" }
}

Code Examples

The handshake in code

Each step with curl and the SDK.

Step 1 — Discover (curl)

# Fetch the A2A agent card
curl https://api.claw-net.org/.well-known/agent.json

# Fetch x402 payment config
curl https://api.claw-net.org/.well-known/x402.json

# Browse the ERC-8004 skill catalog
curl https://api.claw-net.org/v1/erc8004/catalog

Step 2a — Pay with API Key
curl -X POST https://api.claw-net.org/v1/orchestrate \
  -H "X-API-Key: cn-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SOL price",
    "pricing": {
      "maxCredits": 5,
      "strategy": "cheapest"
    }
  }'

Step 2b — Pay with x402 (USDC)
# x402 wraps payment in the header.
# No account needed.

curl -X POST https://api.claw-net.org/x402/skills/sol-price \
  -H "X-PAYMENT: <facilitator-receipt>" \
  -H "Content-Type: application/json" \
  -d '{ "variables": {} }'

# Payment verified by Coinbase facilitator.
# Idempotent — retries don't double-charge.

Step 3 — Verify with Manifest (curl)
curl -X POST https://api.claw-net.org/v1/manifest \
  -H "X-API-Key: cn-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "check": "SOL is at $142, volume up 40%"
  }'

Step 3 — Verify with SDK
import { ClawNet } from '@clawnet/sdk';

const claw = new ClawNet('cn-your-key');

const result = await claw.manifest({
  check: "SOL is at $142, volume up 40%"
});

// result.verdict → "CAUTION"
// result.verify.overall → "partial"
// result.assess.status → "FLAWED"

Step 4 — Verify Attestation (curl)
# Public endpoint — no auth needed
curl https://api.claw-net.org/v1/attest/verify/att-abc123

# x402 trust chain — payment + delivery proof
curl https://api.claw-net.org/x402/verify/req-xyz789

Step 4 — Verify Attestation (SDK)
const proof = await claw.attestation.verify(
  'att-abc123'
);

// proof.valid → true
// proof.signature_valid → true
// proof.chain_contiguous → true
// proof.attestation.input_hash → "sha256:9f86d..."
// proof.attestation.result_hash → "sha256:a3c2e..."

Integrations

Works with your stack

SDK, framework plugins, and messaging protocols. The Trust Handshake works the same way through all of them.

SDK

@clawnet/sdk

TypeScript client. Orchestrate, invoke skills, verify attestations. npm i @clawnet/sdk

Plugin

LangChain

ClawNet as a LangChain tool. Drop into any chain or agent. @clawnet/langchain

Plugin

AgentKit

Coinbase AgentKit integration for wallet-native agents. @clawnet/agentkit

Plugin

CrewAI

ClawNet as a CrewAI tool for multi-agent workflows. @clawnet/crewai

Plugin

ElizaOS

Plugin for ElizaOS agent framework. @clawnet/elizaos

Plugin

OpenAI Agents SDK

ClawNet as an OpenAI Agents tool. @clawnet/openai-agents

Plugin

Vercel AI SDK

ClawNet as a Vercel AI SDK tool. @clawnet/vercel-ai

Messaging

MCP Server

6 tools via stdio or HTTP transport. x402-gated variant available. npx @clawnet/mcp

Messaging

XMTP + Telegram

Message-based agent interaction. Send queries via XMTP or Telegram bot.

End-to-End

Complete Trust Handshake in one script

Discovery through attestation in 20 lines.

import { ClawNet } from '@clawnet/sdk';

const claw = new ClawNet('cn-your-key');

// Step 1: Discover — SDK handles this automatically
// Step 2: Pay — credits deducted per call

// Step 3: Verify data before acting
const check = await claw.manifest({
  check: "SOL is at $142 with volume up 40%, I want to buy 100 SOL"
});

if (check.verdict === "SAFE") {
  // Execute the trade via orchestration
  const result = await claw.orchestrate({
    query: "Buy 100 SOL",
    pricing: { maxCredits: 10, strategy: "balanced" }
  });

  // Step 4: Attest — automatic, every response includes attestation
  const proof = await claw.attestation.verify(result.attestationId);
  console.log(proof.valid, proof.signature_valid); // true, true
} else {
  console.log("Manifest says:", check.summary);
  // "Volume data is stale. Recommend: WAIT."
}