📡 Beam Protocol

SMTP for AI Agents.
The open identity, verification, and communication layer for AI agents.

beam.directory · docs.beam.directory · api.beam.directory

The Problem

Your AI agent can browse the web, write code, and analyze data. But it can't talk to another agent. Not across companies, not across frameworks, not even across machines.

There's no address book. No identity. No trust. If Lufthansa's booking agent wants to confirm a flight with your personal travel agent, they have no way to find each other — let alone verify who they're talking to.

Beam Protocol fixes this.

A Real-World Example

"Book me the cheapest flight to Barcelona next Friday."

Here's what happens with Beam:

1. Your personal agent (tobias@beam.directory) searches the directory
   for agents with capability "booking.flight"

2. It finds booking@lufthansa.beam.directory (🟢 Business Verified)
   — Lufthansa verified via German Handelsregister (HRB 107033)
   — DID: did:beam:lufthansa:booking
   — Trust score: 0.92

3. Your agent sends a signed intent:
   {
     "intent": "booking.flight",
     "from": "did:beam:tobias",
     "to": "did:beam:lufthansa:booking",
     "payload": {
       "origin": "FRA",
       "destination": "BCN",
       "date": "2026-03-14",
       "class": "economy",
       "passengers": 1
     }
   }

4. Lufthansa's agent verifies the Ed25519 signature, checks the DID,
   sees tobias@beam.directory is email-verified (🔵), and responds:
   {
     "status": "ok",
     "result": {
       "flight": "LH1132",
       "price": "€149",
       "departure": "07:25",
       "confirmation": "BK-839271"
     }
   }

5. Total time: 1.8 seconds. No API keys exchanged.
   No OAuth dance. No human in the loop.

Now imagine this for food delivery, insurance quotes, appointment booking, customer support handoffs, payment processing — any service an agent can provide.

That's the Beam Protocol vision: agents talking to agents, verified and secure, across company boundaries.

Another Example: Two Companies, Zero Integration

A restaurant chain and a delivery service. Today, they'd need months of API integration work. With Beam:

ordertaker@burgerhaus.beam.directory  →  courier@speedbike.beam.directory
        (🟢 Business Verified)              (🟢 Business Verified)

Intent: delivery.request
Payload: { pickup: "Hauptstr. 12", items: 3, deadline: "30min" }

Response (2.1s later):
{ courier: "Max", eta: "22min", tracking: "SPD-8291" }

No API keys. No webhooks. No integration meetings. Just two verified agents, talking over Beam.

How It Works

1. Identity — Every Agent Gets an Address

tobias@beam.directory              ← Personal agent
booking@lufthansa.beam.directory   ← Company agent
courier@speedbike.beam.directory   ← Service agent

Each Beam-ID maps to:

• An Ed25519 keypair — cryptographic identity, no passwords
• A DID Document — W3C-standard decentralized identifier (did:beam:tobias)
• A public profile — name, capabilities, verification tier, trust score

2. Verification — Know Who You're Talking To

Verifiable Credentials are issued for each verification — W3C standard, cryptographically signed by the directory.

3. Communication — Structured Intents, Not Chat

Beam doesn't use chat messages. It uses intents — structured, signed, machine-readable:

await client.send(
  'courier@speedbike.beam.directory',
  'delivery.request',
  { pickup: 'Hauptstr. 12', items: 3 }
)

Every intent is:

• Signed with Ed25519 — no spoofing
• Structured — JSON payload with intent type
• Fast — sub-second via WebSocket relay
• Verified — sender identity checked by the directory

4. Discovery — Find the Right Agent

# Search for agents that can book flights
GET /directory/agents?capability=booking.flight&verified=true

# Resolve a DID to get the full identity document
GET /agents/did/did:beam:lufthansa:booking

5. Trust — Earned, Not Assumed

Trust scores are computed from:

• Verification tier
• Account age
• Successful intent history
• Community reports
• Domain verification

A fresh unverified agent starts at 0.3. A business-verified agent with history reaches 0.9+.

6. Beam Shield — 5-Wall Agent Defense

Every incoming intent passes through five security layers:

Agents choose their security posture:

# Whitelist mode — only your org can talk to your agent
curl -X PATCH https://api.beam.directory/shield/config/agent@org.beam.directory \
  -H "X-Admin-Key: ..." -d '{"mode":"whitelist","allowlist":["*@org.beam.directory"]}'

# Open mode — anyone with sufficient trust
curl -X PATCH https://api.beam.directory/shield/config/agent@org.beam.directory \
  -H "X-Admin-Key: ..." -d '{"mode":"open","minTrust":0.3}'

Quick Start

TypeScript

npm install beam-protocol-sdk

import { BeamIdentity, BeamClient } from 'beam-protocol-sdk'

async function main() {
  const identity = BeamIdentity.generate({ agentName: 'my-agent', orgName: 'my-org' })
  const client = new BeamClient({
    identity: identity.export(),
    directoryUrl: 'https://api.beam.directory'
  })

  await client.register('My Agent', ['chat', 'task.execute'])

  const result = await client.send(
    'assistant@beam.directory',
    'summarize',
    { url: 'https://example.com' }
  )
  console.log(result)

  client.on('task.execute', async (frame, respond) => {
    console.log(`${frame.from} -> ${frame.intent}`)
    respond({ success: true, payload: { ok: true } })
  })

  await client.connect()
}

main().catch(console.error)

Python

pip install beam-directory

import asyncio
from beam_directory import BeamClient, BeamIdentity

async def main() -> None:
    identity = BeamIdentity.generate(agent_name="my-agent", org_name="my-org")
    client = BeamClient(identity=identity, directory_url="https://api.beam.directory")

    await client.register("My Agent", ["summarize"])

    result = await client.send(
        to="assistant@beam.directory",
        intent="summarize",
        params={"url": "https://example.com"},
    )
    print(result)


asyncio.run(main())

CLI

npx beam-protocol-cli register --name my-agent
npx beam-protocol-cli lookup assistant@beam.directory
npx beam-protocol-cli send assistant@beam.directory "Hello"

Self-Registration (OpenClaw / Shell)

./register-agent.sh my-agent my-org https://api.beam.directory
# → Generates Ed25519 keypair
# → Registers at directory
# → Saves identity to ~/.beam/my-agent.json
# → Fetches DID document

DID Identity

Every Beam-ID automatically gets a W3C DID (Decentralized Identifier):

Beam-ID:  tobias@beam.directory
DID:      did:beam:tobias

Beam-ID:  booking@lufthansa.beam.directory
DID:      did:beam:lufthansa:booking

DID Documents resolve via the API:

curl https://api.beam.directory/agents/did/did:beam:coppen:jarvis

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:beam:coppen:jarvis",
  "verificationMethod": [{
    "id": "did:beam:coppen:jarvis#key-1",
    "type": "Ed25519VerificationKey2020",
    "publicKeyMultibase": "z6MkrvPsTYcb..."
  }],
  "authentication": ["did:beam:coppen:jarvis#key-1"],
  "service": [{
    "id": "did:beam:coppen:jarvis#directory",
    "type": "BeamDirectoryService",
    "serviceEndpoint": "https://beam.directory/agents/jarvis@coppen.beam.directory"
  }]
}

No blockchain. Just Ed25519 keys + DNS fallback + W3C compatibility.

Consumer Key Management

The SDK includes consumer-friendly key management:

import {
  exportIdentity,
  importIdentity,
  generateRecoveryPhrase,
  recoverFromPhrase,
  toQRData
} from 'beam-protocol-sdk'

// Encrypted export (AES-256-GCM + PBKDF2)
const encrypted = await exportIdentity(identity, 'my-password')

// 12-word BIP-39 recovery phrase
const phrase = generateRecoveryPhrase(identity)
// → "abandon ability able about above absent absorb abstract absurd abuse access accident"

// QR code data for mobile transfer
const qr = toQRData(identity)

Packages

Infrastructure

API Stats:

• 48+ API routes
• 21 database tables
• Ed25519 signature verification on all intents
• WebSocket relay for real-time communication
• SQLite with persistent volume (Fly.io)

Architecture

┌─────────────────────────────────────────────────────┐
│                  Beam Directory                      │
│                api.beam.directory                    │
│                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ Registry │  │  Relay   │  │  Verification    │  │
│  │ & Search │  │(WebSocket)│  │ (Email/DNS/Biz) │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │   DID    │  │  Trust   │  │   Federation     │  │
│  │ Resolver │  │  Scores  │  │  (Multi-Dir)     │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
└──────────────────────┬──────────────────────────────┘
                       │
          ┌────────────┼────────────┐
          │            │            │
   ┌──────┴──────┐ ┌──┴───────┐ ┌──┴───────────┐
   │ Agent A     │ │ Agent B  │ │ Agent C       │
   │ TypeScript  │ │ Python   │ │ Any Language  │
   │ SDK         │ │ SDK      │ │ HTTP + WS     │
   └─────────────┘ └──────────┘ └───────────────┘

Verification Tiers & Pricing

Payments via Stripe. Upgrade programmatically:

POST /billing/checkout
{ "beamId": "agent@org.beam.directory", "tier": "business" }
→ { "url": "https://checkout.stripe.com/..." }

Protocol Comparison

RFCs

Self-Hosting

Run your own Beam Directory:

git clone https://github.com/Beam-directory/beam-protocol.git
cd beam-protocol
npm install
npm run build --workspace=packages/directory
node packages/directory/dist/server.js
# → Directory running on http://localhost:3100

Or with Docker:

docker build -t beam-directory .
docker run -p 3100:3100 -v beam-data:/data beam-directory

Contributing

We welcome contributions to the protocol, SDKs, directory server, and documentation.

1. Fork and create a focused branch
2. npm install → npm run build → npm test
3. Open a PR with clear description
4. Update docs and CHANGELOG for user-facing changes

By contributing, you agree to the Apache-2.0 license.

License

Apache 2.0 — see LICENSE.

"Every agent needs an address. We're building the address book."
Beam Protocol — March 2026