# ERC-8004 Migration Guide — OAuth → Agent Passport

**Status**: Stable · v1.0 · 2026-05-16  
**Audience**: Engineering teams running 5–50 agents currently authenticated via OAuth.  
**Time-to-complete**: 3–6 weeks typical. Below ~50 agents, full migration is usually worthwhile. Above 50, hybrid is fine indefinitely.

---

## Why migrate

OAuth is an authorization protocol. ERC-8004 + delegation proofs is a **trust** layer. Five concrete differences that matter at scale:

| Capability | OAuth | ERC-8004 + delegation proofs |
|---|---|---|
| Identity | scoped to issuer | portable, chain-anchored |
| Revocation | rotate secrets across all trusted apps | single `revoke()` call publishes a revocation proof; ~30s propagation |
| Audit trail | per-app, often inconsistent | append-only ProofDB, HMAC-signed, queryable 18+ months later |
| Sub-agent delegation | none (each sub-agent needs its own OAuth flow) | cryptographic delegation chain, scope-bound |
| Payment | separate from auth | x402 + ecash in the same request |

If you don't need ANY of these, OAuth is fine. If you need **revocation** OR **regulator-facing audit**, migrate.

---

## Three-phase migration

### Phase 1 — Parallel issue (Week 1–2)

Goal: every agent holds BOTH credentials. Nothing breaks; nothing changes on the outside.

1. Mint an ERC-8004 passport per agent via `chainlink-prediction-markets-mcp-enhanced/services/onboarding/agent_onboarding.py` (5-step flow: Register, Verify, Issue Passport, Activate, Attest).
2. Store the passport alongside your existing OAuth tokens in your secret store. Keep OAuth as the active credential.
3. Sign one self-attestation proof per agent and publish to ProofDB — verifies the passport is wired correctly.
4. Rollback path: delete the passport from your secret store. Nothing else changes.

**Smoke test**: `curl https://craigmbrown.com/.well-known/agent-services.json | jq '.trust_layer'` should return a valid trust_layer block with your agent's reputation score visible after the first published proof.

### Phase 2 — Outbound switch (Week 3–4)

Goal: when your agents call OTHER agents, they pay in x402 + sign with their passport, NOT with OAuth.

1. For each outbound HTTP client your agent uses, replace the OAuth header with `X-Agent-Id: <agent_id>` + `X-Passport: <passport_url>` + `X-402-Payment: <ecash_token>` for paid endpoints.
2. Wire `revoke()` into your incident-response runbook. When an agent misbehaves, calling `revoke()` is now a one-line operation — no secret rotation required.
3. Every outbound call now publishes a ProofOfDelegation (kind 30014) to ProofDB.
4. Rollback path: flip the outbound client back to OAuth. Both credentials still valid in Phase 1+2.

**Smoke test**: query ProofDB by your operator_id; expect to see a delegation proof for each outbound call your agents made.

### Phase 3 — Inbound switch (Week 5–6)

Goal: when OTHER agents call YOUR endpoints, they MUST present a passport. OAuth removed.

1. Update your gateway to require `X-Agent-Id` + valid passport hash on inbound. Reject requests without it.
2. Deprecate the OAuth issuer for inbound (keep it running for 14 days as a fallback for any callers you missed announcing the change to).
3. After 14 days, remove the OAuth issuer entirely.
4. Rollback path: re-enable the OAuth issuer at your gateway. Existing passport-authenticated requests continue working in parallel.

**Smoke test**: a known-good agent call from a peer fleet succeeds; an OAuth-only request returns 401 with a JSON body pointing to the migration guide URL.

---

## Decision tree — should you do Phase 3?

```
Are you running >50 agents?
├── No → Phase 3 is usually worth it. Simpler trust model, fewer moving parts.
└── Yes → Are >50% of your inbound callers external (not your own org)?
    ├── No → Phase 3 is still usually worth it (you control the migration cadence).
    └── Yes → Stop at Phase 2. Hybrid (OAuth inbound + ERC-8004 outbound) is fine.
              External callers can adopt passports on their own schedule. You still
              get the audit trail and revocation benefits from Phase 2.
```

---

## Common gotchas

- **Don't migrate during an active incident.** Phase 1 and 2 are safe; Phase 3 is not. Wait for green.
- **Don't share passports across environments.** Each prod/staging/dev agent needs its own. Passport ≠ secret rotation; it's a structural identity.
- **Don't try to migrate calendar / Gmail / external-SaaS OAuth.** ERC-8004 is for agent-to-agent. Keep OAuth for SaaS integrations indefinitely.
- **Do publish a self-attestation proof immediately after passport issuance.** Without it, your agent has a passport but no on-chain reputation accrual.

---

## References

- **Passport schema**: see `.claude/rules/agent-delegation-identity.md` for the full DELEGATION_CONTEXT block format.
- **Onboarding script**: `chainlink-prediction-markets-mcp-enhanced/services/onboarding/agent_onboarding.py`
- **ProofDB query**: see [v5_memory/knowledge/domains/proof-db-agent-guide.md](https://github.com/craigmbrown/blindoracle-docs)
- **x402 specification**: [x402.org](https://www.x402.org/)
- **ERC-8004 draft**: [eips.ethereum.org/EIPS/eip-8004](https://eips.ethereum.org/EIPS/eip-8004)
- **Reading list**: [github.com/craigmbrown/awesome-erc8004](https://github.com/craigmbrown/awesome-erc8004)

---

## Get help

- **Open an issue**: [github.com/craigmbrown/blindoracle-docs](https://github.com/craigmbrown/blindoracle-docs)
- **SDK**: [github.com/craigmbrown/blindoracle-marketplace-client](https://github.com/craigmbrown/blindoracle-marketplace-client)
- **Marketplace rules**: [/blindoracle/marketplace-rules.html](https://craigmbrown.com/blindoracle/marketplace-rules.html)
- **Team FAQ Q10** (this guide answers it): [/blindoracle/faq/team.html#q10](https://craigmbrown.com/blindoracle/faq/team.html#q10)