agent.json Specification

1. Purpose

agent.json answers three questions:

1. What can agents do here? (intents)
2. What inputs do those actions require? (parameters)
3. Where should payment go? (payout address, bounty terms, x402)

Just as robots.txt tells search engines how to crawl a site, agent.json tells AI agents exactly how to interact with your service.

• For Providers: Make your service "agent-ready" in 5 minutes and get paid for agent traffic without maintaining a custom agent API.
• For Runtimes: Stop hardcoding brittle web scrapers. Fetch the agent.json and instantly understand capabilities, inputs, and payment terms.

2. Hosting

Serve your manifest at one of these paths (checked in order):

https://yourdomain.com/.well-known/agent.json    (preferred)
https://yourdomain.com/agent.json                 (fallback)

3. Integration Tiers

Think of tiers like introducing yourself. First you say your name (Tier 1). Then you explain what you do (Tier 2). Then you show your ID to prove it (Tier 3). Each tier unlocks more trust, which is better for economics and agents across the whole ecosystem.

Tier 1 — Minimal

Three fields. Your domain is now discoverable by agent runtimes.

{
  "version": "1.0",
  "origin": "example.com",
  "payout_address": "0x0000000000000000000000000000000000000000"
}

Tier 2 — Structured

Declares specific capabilities. Agent runtimes match user requests to your intents using semantic similarity.

{
  "version": "1.0",
  "origin": "example.com",
  "payout_address": "0x0000000000000000000000000000000000000000",
  "display_name": "Example Store",
  "description": "Online marketplace for electronics and home goods.",
  "intents": [
    {
      "name": "search_products",
      "description": "Search the product catalog by keyword, category, or brand. Returns names, prices, ratings, and availability.",
      "parameters": {
        "query": { "type": "string", "required": true, "description": "Search query" },
        "category": { "type": "string", "required": false, "description": "Product category filter" }
      }
    },
    {
      "name": "complete_purchase",
      "description": "Complete a purchase for items in the user's cart. Requires prior user approval.",
      "parameters": {
        "cart_id": { "type": "string", "required": true, "description": "Cart identifier" }
      },
      "bounty": { "type": "cpa", "rate": 12.00, "currency": "USDC" }
    }
  ],
  "bounty": { "type": "cpa", "rate": 2.00, "currency": "USDC" },
  "incentive": { "type": "cpa", "rate": 0.50, "currency": "USDC" }
}

Tier 3 — Verified Identity

Proves you own your domain with a cryptographic identity. A DID (Decentralized Identifier) lets agents verify your API is legitimate — not an impersonator. The simplest method is did:web: if you own example.com, your DID is did:web:example.com.

Note: Tier 3 proves the API provider's identity. The separate question of whether an agent is authorized to act on a user's behalf is solved by the Open Agent Trust Registry, which verifies that agent runtimes are legitimate — like the Certificate Authority system for the agent internet.

{
  "version": "1.4",
  "origin": "example.com",
  "payout_address": "0x...",
  "identity": {
    "did": "did:web:example.com",
    "public_key": "base64url-encoded-public-key",
    "oatr_issuer_id": "example-runtime"
  },
  "intents": [ ... ],
  "bounty": { ... }
}

Becoming Tier 3: Step by Step

Tier 3 means your API has a provable identity. Instead of just saying "I'm example.com," you can cryptographically prove it. This guide walks you through the process. It takes about 5 minutes.

Step 1: Generate a keypair

Create an Ed25519 keypair. The private key stays secret (you use it to sign things). The public key goes in your agent.json and DID document so others can verify your signatures.

npx @open-agent-trust/cli keygen --issuer-id yourdomain-com

Replace yourdomain-com with a slug based on your domain. Use lowercase letters, numbers, and hyphens only. No spaces. For example: acme-api, stripe, my-saas-co.

This outputs two things:

• Private key — saved as a .private.pem file. Keep this secret. Never commit it to a repo. To read it: cat yourdomain-com.private.pem. macOS users: do not double-click this file. macOS will try to import it into Keychain Access. Always use cat in the terminal.
• Public key — printed to your terminal. This goes in your agent.json and DID document (Steps 2 and 3 below). Safe to share publicly.

Step 2: Add identity to your agent.json

Add the identity block to your existing agent.json. Replace yourdomain.com with your actual domain and paste your public key from Step 1.

"identity": {
  "did": "did:web:yourdomain.com",
  "public_key": "your-public-key-from-step-1",
  "oatr_issuer_id": "your-issuer-id"
}

The did:web method uses your domain as proof of identity. If you control yourdomain.com, you control did:web:yourdomain.com. No registration with a central authority required.

Step 3: Host your DID document

Create a file at /.well-known/did.json on your domain. This is how anyone resolves your DID to find your public key.

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:web:yourdomain.com",
  "verificationMethod": [{
    "id": "did:web:yourdomain.com#key-1",
    "type": "Ed25519VerificationKey2020",
    "controller": "did:web:yourdomain.com",
    "publicKeyMultibase": "z6Mkf5rGMoatrSj1f..."
  }]
}

After deploying, verify it works by visiting https://yourdomain.com/.well-known/did.json in your browser. You should see the JSON above.

Step 4 (optional): Register with the Trust Registry

If you also operate an agent runtime (a platform that runs agents on behalf of users), you can register as a trusted issuer in the Open Agent Trust Registry. This is separate from Tier 3. Tier 3 proves your API's identity. The Trust Registry proves your runtime is authorized to issue attestations for agents.

Key management

4. Field Reference

4.1 Root Object

4.2 Intent Object

Each intent represents one capability the service offers to agents.

When endpoint is present, the intent is a direct API intent. When absent, it's a semantic intent — the runtime uses the description for capability matching and executes via web automation.

4.3 Price Object

What the provider charges to access an intent. Different from bounty (provider pays runtime) and incentive (runtime pays provider).

Example — Paid API:

{
  "name": "analyze_document",
  "description": "AI-powered document analysis. Extracts key clauses, identifies risks, and generates a summary.",
  "endpoint": "/api/v1/analyze",
  "method": "POST",
  "parameters": {
    "document_url": { "type": "string", "required": true, "description": "URL of the document to analyze" },
    "analysis_type": { "type": "string", "required": false, "enum": ["summary", "risk", "full"], "default": "full" }
  },
  "price": {
    "amount": 0.50,
    "currency": "USDC",
    "model": "per_call",
    "network": "base"
  }
}

4.4 Commitmentsv1.4

The commitments block declares behavioral invariants — service-level guarantees that agents and runtimes can use for routing, trust scoring, and enforcement. Commitments can be unsigned (for discovery) or signed with Ed25519 (for tamper-evident enforcement).

Commitment Entry Fields

Example — Commitments with Signature:

{
  "commitments": {
    "schema_version": "1.0",
    "entries": [
      {
        "type": "latency_bound",
        "constraint": "p99 < 500ms",
        "verifiable": true
      },
      {
        "type": "data_residency",
        "constraint": "EU-only processing",
        "verifiable": false
      },
      {
        "type": "uptime_sla",
        "constraint": "99.9% monthly uptime",
        "verifiable": true,
        "ref": "https://example.com/sla.json"
      },
      {
        "type": "regulatory_compliance",
        "constraint": "SOC 2 Type II certified",
        "verifiable": true,
        "ref": "https://example.com/compliance/soc2-2026.pdf"
      }
    ],
    "signature": "base64url-Ed25519-signature"
  }
}

5. Payment Discoveryv1.3

The payments wrapper is a protocol-agnostic object where each key represents a payment protocol. Presence of a key means the provider supports that protocol — no supported: true flag needed.

{
  "payments": {
    "x402": {
      "networks": [
        {
          "network": "base",
          "asset": "USDC",
          "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "facilitator": "https://x402.org/facilitator"
        }
      ]
    },
    "l402": {
      "macaroon_endpoint": "https://api.example.com/l402/macaroon",
      "network": "lightning",
      "currency": "BTC",
      "description": "Pay via Lightning Network"
    },
    "mpp": {
      "provider": "stripe",
      "currency": "USD",
      "checkout_url": "https://example.com/checkout"
    }
  }
}

5.1 Built-in Protocols

5.2 Intent-Level Payments

Each intent can override root-level payment configuration using the same payments wrapper structure.

{
  "name": "analyze_document",
  "description": "AI-powered document analysis.",
  "payments": {
    "x402": {
      "direct_price": 0.50,
      "ticket_price": 0.40,
      "description": "Pay $0.50/analysis directly, or $0.40 with a Session Ticket."
    }
  }
}

6. x402 Field Referencev1.2+

HTTP 402 (Payment Required) is a standard HTTP status code. The x402 protocol builds on this by defining a structured payment challenge and proof mechanism. The x402 object enables agents to discover payment capabilities before making a request.

6.1 Root-Level x402

Declares that this provider supports x402 payment negotiation. These values serve as defaults for all intents.

Single-network (flat):

{
  "x402": {
    "supported": true,
    "network": "base",
    "asset": "USDC",
    "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "facilitator": "https://x402.org/facilitator"
  }
}

Multi-network:

{
  "x402": {
    "supported": true,
    "networks": [
      {
        "network": "base",
        "asset": "USDC",
        "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "facilitator": "https://x402.org/facilitator"
      },
      {
        "network": "arbitrum",
        "asset": "USDC",
        "contract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "facilitator": "https://x402.org/facilitator"
      }
    ]
  }
}

If networks is present, it takes priority and flat fields (network, asset, etc.) are ignored.

6.2 Intent-Level x402 Override

Per-intent x402 metadata. Overrides or extends the root-level x402 configuration for that specific intent.

Example:

{
  "x402": {
    "direct_price": 0.50,
    "ticket_price": 0.40,
    "description": "Pay $0.50/request directly via x402, or $0.40 with a Session Ticket."
  }
}

Resolution order: network_pricing[matching_network] → intent-level direct_price/ticket_price → price.amount

6.3 Full v1.4 Example — Payments, Identity & Commitments

{
  "version": "1.4",
  "origin": "api.example.com",
  "payout_address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "display_name": "Example Intelligence API",
  "description": "AI-powered document analysis API with multi-protocol payments.",
  "identity": {
    "did": "did:web:api.example.com",
    "public_key": "base64url-encoded-Ed25519-public-key",
    "oatr_issuer_id": "example-intelligence"
  },
  "payments": {
    "x402": {
      "networks": [
        {
          "network": "base",
          "asset": "USDC",
          "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "facilitator": "https://x402.org/facilitator"
        },
        {
          "network": "arbitrum",
          "asset": "USDC",
          "contract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
          "facilitator": "https://x402.org/facilitator"
        }
      ]
    },
    "mpp": {
      "provider": "stripe",
      "currency": "USD",
      "checkout_url": "https://api.example.com/checkout"
    }
  },
  "commitments": {
    "schema_version": "1.0",
    "entries": [
      {
        "type": "latency_bound",
        "constraint": "p99 < 500ms",
        "verifiable": true
      },
      {
        "type": "data_residency",
        "constraint": "EU-only processing",
        "verifiable": false
      },
      {
        "type": "uptime_sla",
        "constraint": "99.9% monthly uptime",
        "verifiable": true,
        "ref": "https://api.example.com/sla.json"
      }
    ],
    "signature": "base64url-Ed25519-signature-over-JCS-canonicalized-entries"
  },
  "intents": [
    {
      "name": "analyze_document",
      "description": "AI-powered document analysis. Extracts key clauses, identifies risks, and generates a summary.",
      "endpoint": "/api/v1/analyze",
      "method": "POST",
      "parameters": {
        "document_url": { "type": "string", "required": true }
      },
      "price": {
        "amount": 0.50,
        "currency": "USDC",
        "model": "per_call",
        "network": ["base", "arbitrum"]
      },
      "payments": {
        "x402": {
          "direct_price": 0.50,
          "ticket_price": 0.40,
          "description": "Pay $0.50/analysis directly via x402, or $0.40 with a Session Ticket."
        }
      }
    }
  ],
  "bounty": { "type": "cpa", "rate": 0.25, "currency": "USDC" }
}

7. Economic Flows

All three can coexist in the same manifest. A service can receive user payments for API calls (price), offer a routing bounty to agents who bring traffic (bounty), and request a performance payment from the runtime (incentive).

Payment Rail Support

• x402 (HTTP 402) — On-chain micropayments via payment challenges. Declared in payments.x402.
• L402 (Lightning) — Lightning Network micropayments via macaroon auth. Declared in payments.l402.
• MPP (Managed) — Traditional processors (Stripe, Square). Declared in payments.mpp.
• Direct transfer — Agents send payment directly to payout_address.
• Custom protocols — Any protocol via custom keys in payments. Spec doesn't need to change.

8. Versioning

The version field uses "MAJOR.MINOR" format.

• Major changes (1.0 → 2.0) indicate breaking changes.
• Minor changes (1.0 → 1.1) indicate backward-compatible additions.

9. Security Considerations

• Origin verification is mandatory. Runtimes must reject manifests where the origin doesn't match the serving domain.
• HTTPS is mandatory. Runtimes must not fetch manifests over HTTP.
• Intent descriptions are untrusted input. Runtimes should not execute them as code or use them where injection is possible.
• Endpoint URLs must be same-origin. A manifest at example.com should not declare endpoints at evil.com.
• API secrets never appear in the manifest. The manifest is public. All secrets live server-side.
• Manifests can change. Providers can modify at any time. Runtimes should re-fetch periodically and handle changes gracefully.