Entity Engagement Protocol (EEP)

An open standard for push-based, verifiable communication between digital entities and the clients that follow them.

Stability (v0.1)

The specification and reference packages are v0.1: the spec, schemas, CI and libraries here are meant to be implemented against, but breaking changes can still happen while the ecosystem is small. Pin versions in production and read CHANGELOG.md before upgrades. Governance details: GOVERNANCE.md.

Community and safety: Code of Conduct · Security (reports: [email protected] with [Security] in the subject) · Releasing (maintainers)

Origins

EEP grew out of engineering work at more.md, where the team built a platform around the idea of one canonical URL per digital entity. Once the protocol stabilized, it was extracted from that codebase, generalized and open-sourced under Apache 2.0 so any publisher and any agent can speak the same wire format. The more.md team continues to maintain the specification alongside the rest of the core team listed in GOVERNANCE.md and operates the production reference implementation that exercises every conformance tier and gate type defined here.

EEP?

MCP, A2A, webhooks and ActivityPub standards solve different problems. EEP composes with all of them.

• MCP lets an LLM call a tool. EEP lets an LLM follow an entity over time — discover it, subscribe and react to verified events from it.
• A2A lets two agents collaborate on a task. EEP defines how either agent learns that an entity changed at all.
• Plain webhooks require a custom protocol per publisher (auth, signing, retries, replay window). EEP is one wire format with HMAC-signed delivery, SSE and a 60-second replay window — implemented once, reusable everywhere.
• ActivityPub federates accounts in a social graph. EEP delivers state-change events from any entity (person org, agent, product, listing) to authorized subscribers, with optional payment / credential / identity gates.
• DIDs and Verifiable Credentials identify who an entity is. EEP defines what they tell their subscribers and how subscribers verify it.

If you are building anything labelled "agentic," EEP is the missing layer between the agent knows about the world (DIDs, MCP, your data store) and the agent reacts when the world changes (today: bespoke per-vendor integrations).

Official repositories

• Protocol and reference code: github.com/eep-dev/EEP
• Landing site: github.com/eep-dev/eep-site

In this repository

If you are deciding whether to star, fork or integrate, here is what is actually here:

Nothing here promises a particular ranking, traffic or business outcome. It does promise a documented wire format, libraries you can import and commands you can run to check behavior.

What is EEP?

The Entity Engagement Protocol (EEP) describes how digital entities (people organizations, products, agents) publish state changes and how authorized subscribers receive them as events, with optional access gates (identity, credentials, payment, agreements) and signatures so subscribers can tell real traffic from forgery.

Much of the web still relies on polling or bespoke feeds, so clients often see stale data or one-off integrations. EEP standardizes discovery, subscription, delivery (SSE and webhooks at minimum) and optional WebSocket negotiation so integrations look the same across publishers.

The triple protocol

EEP defines three transport layers for different jobs:

Implementations must provide the signal stream. State resolution and network pulse are optional add-ons.

Why it exists

Automated clients (mobile apps, backends or agents) repeatedly hit the same problems: knowing when something changed, subscribing without a custom protocol per publisher and checking that an event really came from that entity. EEP combines shared discovery, push delivery and cryptographic checks.

Publishers and strategists: structured discovery, manifests versus sitemaps and generative engine optimization (GEO) are discussed as industry context in the Whitepaper and non-normative spec notes. GEO is not a conformance test for EEP.

Protocol positioning

EEP is the contract for agent ↔ entity engagement: discovery, realtime streams, gate proofs and payment-aware access. It sits next to other stacks.

See eep-positioning-complementary.md for a short comparison.

Quick start

Bootstrap (contributors and CI)

bash scripts/bootstrap.sh

Testing

Run the test matrix: TESTING.md

bash test.sh

To run the full test matrix including cross-implementation network tests (this implicitly starts a background server):

bash test.sh --full

For subscribers (sketch)

# Subscribe to an entity stream (webhook delivery)
curl -X POST https://api.example.com/eep/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_did": "did:web:example.com:u:acme-corp",
    "event_types": ["com.example.entity.updated", "com.example.trust.changed"],
    "delivery_method": "webhook",
    "delivery_url": "https://your-agent.example.com/hooks/eep"
  }'

# Or open an SSE stream (no webhook)
curl -N "https://api.example.com/eep/stream?source=acme-corp" \
  -H "Authorization: Bearer YOUR_API_KEY"

For platforms (dispatchers)

How to dispatch walks through emitting EEP events from your own stack.

Setup CLI (init, inject, apply)

Use @eep-dev/setup-cli to scaffold a new config (init) or analyze an existing service (inject), then generate artifacts (apply) and validate (verify, doctor, status, rotate-secrets). After apply, you still mount routes in your app: After setup-cli: wire EEP into your app.

cd packages/@eep-dev/setup-cli
npm install
npm run build   # optional; otherwise use npx tsx below

node dist/index.js init --preset exchange --out ./eep-setup.json
# same as: npx eep-setup init …  (after build, from this package directory)
# or: npx tsx src/index.ts init --preset exchange --out ./eep-setup.json

npx tsx src/index.ts inject --project /path/to/existing-api --out /path/to/existing-api/eep-setup.json
npx tsx src/index.ts apply --config /path/to/existing-api/eep-setup.json --dry-run
npx tsx src/index.ts apply --config /path/to/existing-api/eep-setup.json --output /path/to/existing-api/eep-generated
npx tsx src/index.ts verify --output /path/to/existing-api/eep-generated
npx tsx src/index.ts doctor --output /path/to/existing-api/eep-generated
npx tsx src/index.ts status --output /path/to/existing-api/eep-generated
npx tsx src/index.ts rotate-secrets --env /path/to/existing-api/.env

Runtime integration: Node @eep-dev/middleware, Python eep-middleware-python.

WebSocket (network pulse)

// Bidirectional channel for negotiation-style work
const ws = new WebSocket('wss://api.example.com/eep/pulse', {
  headers: { Authorization: `Bearer ${API_KEY}` }
});

ws.onopen = () => ws.send(JSON.stringify({
  v: 1, type: 'system', action: 'subscribe',
  data: { source_did: 'did:web:example.com:u:acme-corp' }
}));

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  console.log(`[${msg.type}] ${msg.action} (seq: ${msg.seq})`);
};

Repository layout

EEP/
├── docs/                              # Spec, guides, ops baselines
│   ├── index.md
│   ├── current/                       # SPECIFICATION.md, MONETIZATION.md, security, delivery_guarantees
│   ├── ops/                           # SLO, incidents, webhooks, observability
│   └── guides/                        # Subscribe, dispatch, testing, enterprise, agents, setup-cli, …
├── schemas/v0.1/                      # JSON Schemas for v0.1
├── packages/
│   ├── @eep-dev/{signer,validator,gates,compliance-cli,discovery,mcp-bridge,middleware,setup-cli}
│   └── eep-*-python/                  # Python ports (naming: eep-gates, eep-signer, …)
├── tests/                             # Schema tests, benchmarks, parity tests
│   └── cross-impl/                   # Pytest suite against any EEP publisher (see README there)
├── realworld-simulation/            # Next.js + Express “Old Web vs EEP” demo
├── scripts/                         # bootstrap.sh, smoke tests, coverage helpers
├── examples/
│   ├── eep-reference-implementation/# Docker: Node + Python APIs + Postgres + Redis
│   ├── eep-middleware-express-mini/   # Minimal middleware wiring
│   ├── node-express-subscriber/
│   ├── node-gate-publisher/
│   ├── python-fastapi-subscriber/
│   ├── python-gate-subscriber/
│   └── cross-impl/                    # Legacy interoperability harness (see its README)
├── test.sh                            # Aggregated test entry
└── TESTING.md                         # Detailed test commands

Packages (summary)

Shipped as npm packages (TypeScript, Node 18+ where noted) with Python counterparts for the same roles:

• @eep-dev/signer / eep-signer: HMAC-SHA256 webhook signing and verification (Standard Webhooks aligned usage).
• @eep-dev/validator / eep-validator: SSRF checks on subscriber URLs and event-type pattern matching before you call out.
• @eep-dev/gates / eep-gates: gate configs, access resolution, HTTP 402 helpers, commerce transitions.
• @eep-dev/compliance-cli / eep-compliance-cli: point at a live base URL and run conformance probes (Node CLI targets Node 22+).
• @eep-dev/discovery / eep-discovery: manifest validation, Link headers, DNS TXT.
• @eep-dev/mcp-bridge / eep-mcp-bridge: bridge MCP tool traffic with EEP.
• @eep-dev/middleware / eep-middleware-python: drop-in HTTP adapters (Express, Fastify, Hono, Koa; FastAPI, Flask, Django).
• @eep-dev/setup-cli: project detection, codegen, verify/doctor/watch.
• @eep-dev/agent-adopt: one-shot inject + apply + verify, optional framework patch, EEP_ADOPTION_REPORT.md.

@eep-dev/signer

import { EEPSigner, verifyEEPWebhook } from '@eep-dev/signer';

const sig = new EEPSigner(secret).sign(webhookId, timestamp, body);
const ok = verifyEEPWebhook(rawBody, req.headers, secret);

@eep-dev/validator

import { validateSSRF, matchesAnyPattern } from '@eep-dev/validator';

await validateSSRF(deliveryUrl); // throws if unsafe
const match = matchesAnyPattern('com.example.entity.updated', ['com.example.entity.*']);

@eep-dev/compliance-cli

npx @eep-dev/compliance-cli --target https://api.yourplatform.com --api-key sk_... --entity u/test

Probes cover discovery, subscription, WebSub verification, signatures, CloudEvents envelopes, SSE and rate-limit headers. Use --report-json / --report-md for CI artifacts.

@eep-dev/discovery

Manifest validation, Link header parsing and DNS TXT parsing for discovery documents.

@eep-dev/gates

import { parseGateConfig, resolveAccess, build402Response, transition, ProofVerifierRegistry } from '@eep-dev/gates';

const config = parseGateConfig(entityGateJson);
const registry = new ProofVerifierRegistry();
registry.register({
  supportedTypes: ['payment'],
  verify: async (proof) => Boolean((proof as { token?: string }).token),
});

const result = await resolveAccess(agentProofs, config, 'content.papers.full_text', registry);
if (!result.granted) {
  const body = await build402Response(config, 'content.papers.full_text', agentProofs);
}

const t = transition('open', 'accept'); // { valid: true, to: 'accepted' }

Tier types include payment, trust, identity, credential, connection, capability, allowlist, reciprocal, custom x-* and combined tiers (see spec and tests for exact rules).

Reference deployment

EEP ships with two reference deployments at different levels of completeness:

• In-tree minimal stack — examples/eep-reference-implementation/. A small Node + Python + Postgres + Redis Compose project used by contributors and CI to exercise Layer 1 discovery, Layer 2 subscribe/stream, Layer 3 pulse and the gate endpoints against shared parity fixtures. Smoke script from repo root: bash scripts/eep-reference-smoke.sh (see Five-minute proof).
• Production reference — more.md — the platform where EEP originated. It runs every conformance tier (Core, Standard, Full), all gate types (credential, identity, agreement, data_request, payment, trust, allowlist, reciprocal, custom x-*), the commerce state machine and the WebSocket pulse end-to-end in production. Implementors who want to see EEP exercised at full scope can point clients and @eep-dev/compliance-cli at a more.md endpoint.

The minimal stack is sufficient to read the spec and run conformance probes locally; more.md is the reference for what a complete EEP deployment looks like in production.

Conformance levels

npx @eep-dev/compliance-cli --target https://api.yourplatform.com

Publishers should enforce per-subscriber 429 limits with Retry-After and X-RateLimit-*; numeric quotas stay implementation-defined.

Governance and planning

EEP uses a BDFN model for 0.x and plans a steering committee at v1.0. Details: GOVERNANCE.md.

• ROADMAP.md — milestones for v0.2, v0.3 and v1.0 (TSC formation, IETF/W3C submission, foundation transition)
• MAINTAINERS.md — current maintainer tiers and per-package ownership
• CHANGELOG.md — Keep-a-Changelog-style release notes
• eep-site sync checklist — keep landing-site copy in lockstep with the spec
• arXiv packaging notes — for the whitepaper
• ADOPTERS.md — optional public list; PRs welcome

Roadmap and adoption

Completed in-tree:

• Python ports for gates, signer, validator, compliance CLI, discovery, MCP bridge and middleware (see packages/eep-*-python/).
• Cross-implementation HTTP tests (tests/cross-impl).
• Python gate subscriber example (examples/python-gate-subscriber).

Further reading:

• How to use the Setup CLI
• After setup-cli: wire EEP into your app
• Five-minute proof
• Realworld simulation and realworld-simulation/README.md
• Enterprise implementation playbook
• Agent onboarding

Contributions: CONTRIBUTING.md.

License

Apache 2.0. See LICENSE.