OBSERVER PROTOCOL · DOCS
Developer Documentation · v1.3

Documentation

Everything you need to register agents, issue credentials, verify identity, and integrate Observer Protocol into your stack. Open protocol, MIT licensed, self-hostable.

On This Page
Getting Started API Reference SDK DID Resolver Spec & AIP DID Resolution
Getting Started

Choose your path.

Get started with Observer Protocol. Full developer documentation, SDK reference, and working examples on GitHub.

📖
START HERE
Developer Guide
Architecture · API Reference · Chain Verification
Complete developer documentation on GitHub. Covers agent registration, chain-agnostic verification, trust scoring, VAC extensions, and sandbox testing.
⚡
60 SECONDS
Agent Quickstart
Python · pip install observer-protocol
Register an agent, prove key ownership, retrieve your VAC, and check your trust score — all in 60 seconds. Working code you can run immediately.
🔗
CHAIN-AGNOSTIC
Chain Verification
x402 / USDC · Lightning · TRON · Solana · ERC-8004
Verify transactions on any supported rail. x402 dual verification (Coinbase facilitator + Base RPC). Lightning three-tier model. TRON TronGrid verification. Solana Ed25519. ERC-8004 / TRC-8004 on-chain registry integration.
📦
NPM INSTALL · v0.2.0
TypeScript SDK
npm install @observer-protocol/sdk
Full TypeScript SDK: agent identity, delegation, x402 verification, magic link authorization, chargeback prevention, ERC-8004 integration. Zero dependencies. Browser + Node.js.
🐍
PIP INSTALL · v0.2.0
Python SDK
pip install observer-protocol
Full Python SDK: agent identity, delegation, x402 verification, magic link authorization, chargeback prevention, ERC-8004 integration. Type-hinted throughout.
🏗️
FOR NETWORKS
Network Operator Guide
Platforms · Marketplaces · Networks
Integration path for platforms wanting to verify agent transactions, write to the audit trail, and register VAC extensions for their reputation data.
API Reference

API v1.3 — Base URL: api.observerprotocol.org

All non-DID endpoints use the /api/v1/ prefix. DID document paths follow the W3C did:web resolution standard and are documented separately below. Full interactive documentation available via Swagger UI.

Interactive Swagger UI ↗ OpenAPI YAML ↗
Agent Identity
POST/observer/register-agentRegister agent
POST/observer/challengeGet challenge
POST/observer/verify-agentVerify identity
GET/observer/agents/{agent_id}Agent profile
PATCH/api/v1/agents/{agent_id}Update agent
DID Resolution
GET/api/v1/resolve/{did}Resolve any did:web NEW
POST/observer/consolidate-identityCross-rail consolidation
GET/vp/verifyVerify VP NEW
POST/vp/submitSubmit VP NEW
Verifiable Agent Credentials
GET/vac/{agent_id}Get VAC
POST/vac/{agent_id}/refreshRefresh VAC
GET/vac/{agent_id}/historyVAC history
POST/vac/partners/{id}/attestIssue attestation NEW
GET/vac/partnersPartner registry
AIP v0.5 NEW
POST/aip/credentials/delegationIssue delegation VC
POST/aip/credentials/kybIssue KYB VC
GET/aip/chain/verify/{id}Verify chain
POST/aip/revokeRevoke + cascade
POST/aip/remediation/buildBuild remediation
GET/aip/type-registry/{category}Type registry
Protocol Activity
GET/api/v1/healthHealth check
GET/api/v1/statsAggregate stats
GET/observer/feedVerified event feed
GET/observer/trendsProtocol trends
POST/observer/submit-transactionSubmit transaction
Organizations
GET/api/v1/protocolsList protocols
GET/api/v1/metricsTime-series metrics
GET/api/v1/signalsProtocol signals
GET/observer/badge/{agent_id}.svgAgent badge SVG
Try It Live · DID Resolution
# Enter a DID above and click Resolve. # Endpoint: GET https://api.observerprotocol.org/api/v1/resolve/{did} # # Example DIDs: # did:web:observerprotocol.org:agents:maxi-0001 # did:web:observerprotocol.org:agents:vicky-0002
# Resolve any did:web DID document
curl https://api.observerprotocol.org/api/v1/resolve/did:web:observerprotocol.org:agents:maxi-0001

# Returns W3C DID Document with verification methods and service endpoints
SDK

@observerprotocol/sdk

JavaScript SDK for cryptographically verifiable agent identity. Node 16+, MIT license.

# Install pip install observer-protocol # or npm install @observer-protocol/sdk # Register your agent const { ObserverProtocol } = require('@observerprotocol/sdk'); const observer = new ObserverProtocol(); const agent = await observer.registerAgent({ publicKey: '02a1b2...', alias: 'MyAgent' }); // Returns agent_did, badge_url, did_document_url
⚠
# Verify agent identity const verified = await observer.verifyAgent( agent.id, challenge, signature ); # Record a transaction await observer.recordTransaction({ senderId: agent.id, paymentHash: hash, proof: preimage }); # Get VAC const vac = await observer.getVAC(agent.id);
GitHub → sdk-js ↗ npm ↗
Spec & AIP

Open standards. Versioned specs.

Observer Protocol is governed by open specifications maintained on GitHub. AIP v0.5.1 is deployed as of April 27, 2026 — includes chargeback prevention, x402 support, and magic-link authorization.

PROTOCOL SPEC · CC BY 4.0

Observer Protocol Spec

The canonical specification for OP — identity model, event schema, verification logic, VAC structure, and API reference. Version controlled on GitHub.

github.com/observer-protocol/observer-protocol-spec ↗
AIP v0.5.1 · UPDATED APRIL 27, 2026

Agent Interaction Protocol

AIP governs how agents interact — delegation credentials, magic-link authorization, settlement receipts, chargeback prevention, and type registry.

Read AIP v0.5.1 spec ↗
OPENAPI · OAS 3.0

API OpenAPI Spec

Machine-readable API specification in OpenAPI 3.0 format. Use to generate client SDKs, validate requests, or power your own Swagger UI instance.

API-SPEC-OPENAPI.yaml ↗
CANONICAL REFERENCE · PERMANENT URL

Architecture Document

The permanent citable reference for grants, investor materials, developer documentation, and academic reference. Updated April 2026.

observerprotocol.org/architecture ↗
W3C JSON SCHEMAS · LIVE URLS

Credential Schemas

X402PaymentCredential, Delegation v2 (three-level authorization), Settlement Receipt v1 (chargeback prevention). All $id URLs resolve.

observerprotocol.org/schemas/ ↗
ON-CHAIN REGISTRY · LIVE

ERC-8004 / TRC-8004 Integration

On-chain agent identity and reputation registry integration. Indexers for Base and TRON mainnet, cross-registry DID resolution, registration file pinning, and OP validator on Base.

rails/erc8004/ on GitHub ↗
DEMO · THOUGHT LEADERSHIP

Chargeback Prevention Demo

End-to-end demo: agent purchase, magic-link authorization, settlement receipt, cryptographic dispute prevention. For AI infrastructure companies.

observerprotocol.org/chargeback-prevention ↗
DID Resolution · Reference

How did:web resolution works on OP.

Observer Protocol uses the W3C did:web method. DID Documents are served at standard URL patterns — not through the API. This is intentional: DID resolution is a protocol-level concern, not an API endpoint.

AGENT DID PATTERN
did:web:observerprotocol.org:agents:{agent_id}
→ resolves to:
https://observerprotocol.org/agents/{agent_id}/did.json
ORG DID PATTERN
did:web:{org-domain}:op-identity
→ resolves to:
https://{org-domain}/op-identity/did.json
ROOT DID PATTERN
did:web:observerprotocol.org
→ resolves to:
https://observerprotocol.org/.well-known/did.json

The W3C did:web method transforms a DID into an HTTPS URL by replacing colons with forward slashes. Anyone with HTTPS access can resolve an OP DID without querying the OP API — this is what makes agent identity truly portable.

The domain mismatch rule: an agent's DID domain must match its organization's DID domain. A mismatch is treated as a fraud signal by AIP-compliant implementations.

DID Component Resolves To
did:web:example.comhttps://example.com/.well-known/did.json
did:web:example.com:agents:abchttps://example.com/agents/abc/did.json
did:web:example.com:op-identityhttps://example.com/op-identity/did.json
Compatible with DIF Universal Resolver · W3C DID Core spec · did:web method spec