v1.0.0 · Open Source

Every agent responds.
PactSpec tells you which ones to trust.

“After MCP dropped, I wired up a dozen tool servers to a workflow I was building. The protocol worked — every tool responded. But I had no idea if the responses were actually correct, what anything cost, or who to blame when things broke at 2am. MCP solved the plumbing. Nobody was solving the trust problem. So I started building PactSpec.”

PactSpec is an open, machine-readable format for declaring what an AI agent does, proving it works, and stating what it costs. The spec is completely standalone — validate offline, publish to any registry, or self-host.

JSON Schema GitHub

The problem

There are already thousands of AI agents. By next year there will be millions. An orchestrator that needs to process an invoice has dozens of options — but no standard way to answer three basic questions:

Does it work?

No test results, no benchmarks, no verification

What does it cost?

No pricing metadata, no payment protocol

Who built it?

No provider identity, no audit trail

Minimal example

A valid PactSpec file only needs seven fields. Everything else is optional.

{
  "specVersion": "1.0.0",
  "id": "urn:pactspec:acme:summarizer",
  "name": "Acme Summarizer",
  "version": "1.0.0",
  "provider": { "name": "Acme Corp" },
  "endpoint": { "url": "https://api.acme.dev/summarize" },
  "skills": [
    {
      "id": "summarize",
      "name": "Summarize Text",
      "description": "Summarizes input text to a concise paragraph",
      "inputSchema": {
        "type": "object",
        "required": ["text"],
        "properties": { "text": { "type": "string" } }
      },
      "outputSchema": {
        "type": "object",
        "required": ["summary"],
        "properties": { "summary": { "type": "string" } }
      }
    }
  ]
}

Save as agent.pactspec.json. That's a complete, valid spec.

Spec structure

specVersion"1.0.0"Schema version.

idstringURN identifier: urn:pactspec:{provider}:{agent-name}

namestringHuman-readable name (max 100 chars).

versionstringSemver (e.g. "2.1.0").

providerobjectWho operates this agent. Required: name.

endpointobjectWhere to call it. Required: url.

skillsarrayWhat it does. Typed I/O schemas per skill.

descriptionstringWhat the agent does. Optional.

tagsstring[]Searchable tags. Optional.

delegationobjectIf this wraps another agent. Optional.

interopobjectMCP, ACP, or OpenAPI metadata. Optional.

Full schema: /api/spec/v1

Skills, schemas & tests

Each skill declares typed input and output using JSON Schema. A testSuite URL points to HTTP roundtrip tests any validator can run against the live endpoint.

{
  "id": "classify-icd11",
  "name": "ICD-11 Medical Classifier",
  "description": "Maps clinical text to ICD-11 codes",
  "inputSchema": {
    "type": "object",
    "required": ["text"],
    "properties": { "text": { "type": "string", "maxLength": 5000 } }
  },
  "outputSchema": {
    "type": "object",
    "required": ["code", "description"],
    "properties": {
      "code": { "type": "string" },
      "description": { "type": "string" },
      "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
    }
  },
  "testSuite": {
    "url": "https://api.acme.dev/tests/classify-icd11.json",
    "type": "http-roundtrip"
  }
}

Pricing

Skills can declare pricing. Consumers know what they'll pay before they call. The registry verifies the declared price matches what the endpoint actually charges.

"pricing": {
  "model": "per-invocation",
  "amount": 0.05,
  "currency": "USD",
  "protocol": "stripe"
}

free

No cost

per-invocation

Flat fee per call

per-token

LLM-style token billing

per-second

For long-running tasks

Currencies: USD, USDC, SOL. Protocols: stripe, x402, none.

PactSpec ships middleware that handles the payment flow: Stripe (metered billing, checkout sessions, free quotas) and x402 (HTTP 402 micropayments with on-chain verification on Base/Solana).

Offline validation

The CLI validates entirely offline. No network, no registry, no account.

npm install -g @pactspec/cli

pactspec init -i                    # interactive setup
pactspec validate agent.pactspec.json  # offline schema check
pactspec test agent.pactspec.json      # run tests against live endpoint
pactspec publish agent.pactspec.json   # optional — for registry discovery
pactspec badge agent.pactspec.json     # get a README badge (copies to clipboard)

Discovery without a registry

Agents can serve their spec at /.well-known/pactspec.json for direct discovery.

import { pactspec } from '@pactspec/register';

app.use(pactspec({
  name: 'Acme Summarizer',
  provider: { name: 'Acme Corp' },
  skills: [{ /* ... */ }]
}));
// Serves spec at GET /.well-known/pactspec.json
// Direct agent-to-agent discovery. No registry needed.

Federation & custom registries

The CLI defaults to pactspec.dev but accepts any registry URL.

pactspec publish agent.json
pactspec publish agent.json --registry https://registry.internal.acme.dev

The registry is a discovery layer, not a runtime dependency

Agents are invoked directly at their endpoint URL. The registry is never in the request path. If it goes down, every agent keeps working.

Interoperability

PactSpec complements existing protocols — it doesn't replace them.

Capability	OpenAPI	MCP	PactSpec
Skill-level I/O schemas	✓	✓ input only	✓ input + output
Pricing	✗	✗	✓ model + amount + protocol
Test suites	✗	✗	✓ HTTP roundtrip tests
Verified records	✗	✗	✓ Ed25519 signed results
Public registry	~ commercial	✗	✓ open
Payment handling	✗	✗	✓ x402 + Stripe

MCPModel Context Protocol

MCP handles transport. PactSpec adds verification, pricing, and discovery. The CLI can convert MCP tool definitions to PactSpec skills.

OpenAPI

Link your existing OpenAPI spec via interop.openapi. The CLI can scaffold a PactSpec from an OpenAPI document.

Trust boundaries

PactSpec is honest about what it can and can't verify.

Pricing verification is point-in-time

The registry calls the endpoint and compares what it charges to what the spec declares. This catches accidental mismatches but is not a strong anti-fraud mechanism.

Delegation is self-declared

The registry records that one agent wraps another but does not independently verify the upstream relationship.

Verification is registry-run

Health checks and benchmarks are executed by the registry directly against the live endpoint. No self-reported metrics. Benchmarks are authored by domain experts, not PactSpec. Every result is reproducible — run pactspec test yourself and get the same score.

FAQ

What if pactspec.dev goes down?

Your agents keep working. The registry is a discovery layer, not a runtime dependency. Agents are invoked directly at their endpoints. The spec is open, and anyone can run their own registry.

Why trust it?

Every result is reproducible. Run pactspec test yourself. Results are signed with Ed25519 — verify with the public key at /api/registry-key. The spec is open, the code is on GitHub, and nothing requires you to use our registry.

The spec is open. The schema is public. Use it however you want.

Publish an agent Download schema GitHub

Every agent responds.PactSpec tells you which ones to trust.