How do I authenticate with the PostBridge API?

PostBridge supports three auth methods: x402 (pay per request with USDC on Base L2, zero signup), UCAN (W3C DID-based capability tokens with delegation), and traditional API keys (register with email, get pb_live_ key).

What countries does PostBridge support for sending letters?

PostBridge supports 5 countries: United States (First Class, Certified, Priority), France (Lettre Verte, Suivie, LRAR), United Kingdom (1st/2nd Class, Signed For, Special Delivery), Canada (Lettermail, Registered, Priority), and Germany (Standardbrief, Einschreiben).

How do I send a letter using the PostBridge API?

Three steps: 1) Sign up via POST /auth/register or use x402 (no signup needed). 2) Get a quote via POST /api/quote. 3) Send the letter via POST /api/send with recipient address, sender address, service type, and content. Track delivery with GET /api/track/{letter_id}.

PostBridge AI — Developer API Reference | Send Physical Mail via API, MCP, Olas Mech

Authentication

Three options — pick what fits your stack. x402 is recommended for AI agents.

x402 — Zero Signup (Recommended)

Pay per API call with USDC on Base L2. No signup, no API key, no wallet top-up. The payment IS the authentication. 2.5% commission.


                    Hit any paid endpoint → HTTP 402 → sign USDC payment → retry with:

                    X-PAYMENT-SIGNATURE: <signed USDC TransferWithAuthorization>

Protocol: x402 · Network: Base L2

UCAN — Decentralized Auth

W3C DID-based capability tokens with delegation chains. Issue once, delegate to sub-agents. Escalation-proof. Verify offline.


                    Authorization: Bearer ucan:eyJhbGciOiJFZERTQSIs...

Standards: W3C DID · UCAN 0.10.0 · Ed25519

API Key — Traditional


                    Authorization: Bearer pb_live_xxxxxxxxxxxxxxxx

Commission: 2.5% crypto · 5% fiat

Quick Start

Send your first physical letter in 3 API calls. See how AI agents use PostBridge for the full platform overview.

curl
# 1. Sign up (skip if using x402)
curl -X POST https://api.postbridge.ai/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@company.com", "name": "Your Name"}'
# Save the api_key from the response — shown once only

# 2. Get a price quote
curl -X POST https://api.postbridge.ai/api/quote \
  -H "Authorization: Bearer pb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_name": "Jane Doe",
    "to_line1": "123 Main St",
    "to_city": "New York",
    "to_postal_code": "10001",
    "to_country": "US",
    "service": "us_first_class",
    "payment_method": "usdc"
  }'

# 3. Send the letter
curl -X POST https://api.postbridge.ai/api/send \
  -H "Authorization: Bearer pb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_name": "Jane Doe",
    "to_line1": "123 Main St",
    "to_city": "New York",
    "to_state": "NY",
    "to_postal_code": "10001",
    "to_country": "US",
    "from_name": "Your Company",
    "from_line1": "456 Oak Ave",
    "from_city": "San Francisco",
    "from_state": "CA",
    "from_postal_code": "94107",
    "from_country": "US",
    "service": "us_first_class",
    "content": "<p>Dear Jane, your order has shipped.</p>",
    "payment_method": "usdc"
  }'
# Response includes letter_id for tracking

# 4. Track delivery
curl https://api.postbridge.ai/api/track/LETTER_ID \
  -H "Authorization: Bearer pb_live_YOUR_KEY"
        

REST API Endpoints

Base URL: https://api.postbridge.ai

Public (No Auth Required)

Method	Endpoint	Description
GET	`/`	Service info — name, version, status, available endpoints
GET	`/health`	Health check — returns `ok` + timestamp
GET	`/x402`	x402 payment protocol status, supported methods, quickstart
GET	`/auth/scopes`	List available API key scopes: `full`, `send`, `read`

Auth — Registration & Keys

Method	Endpoint	Description
POST	`/auth/register`	Register with email → returns one-time API key public
POST	`/auth/agent`	AI agent auto-provision — no email needed public
POST	`/auth/keys`	Create a new API key with label and scope full
GET	`/auth/keys`	List active API keys (prefix only) full
DELETE	`/auth/keys/{id}`	Permanently revoke an API key full
POST	`/auth/keys/{id}/rotate`	Rotate key — old dies, new issued with same scope full

Postal Services — US, FR, GB, CA, DE

Method	Endpoint	Description
GET	`/api/services/{country}`	List postal services for a country. Returns services, tracking, proof options. read
POST	`/api/quote`	Get price breakdown: postage + print + commission + total read

Letters — Send, Track, Manage

Method	Endpoint	Description
POST	`/api/send`	Send a physical letter. Provide `content` (text/HTML) or `document_url` (PDF). send
GET	`/api/letters`	List all letters. Filter: `?status=queued\|delivered\|cancelled` read
GET	`/api/letters/{id}`	Full letter details: addresses, pricing, tracking, status read
PATCH	`/api/letters/{id}`	Update recipient or reference. Only `draft`/`queued` letters. send
POST	`/api/letters/{id}/cancel`	Cancel letter + full refund to wallet send
DELETE	`/api/letters/{id}`	Delete record (only cancelled/failed/draft) send

Tracking & Proof

Method	Endpoint	Description
GET	`/api/track/{letter_id}`	Live delivery status. Flow: queued → processing → posted → in_transit → delivered read
GET	`/api/proof/{letter_id}`	Audit-ready proof of sending/delivery for legal compliance read

Wallet & Payments

Method	Endpoint	Description
GET	`/api/balance`	Current USD balance + last 10 transactions read
POST	`/api/topup`	Top up wallet via USDC, BTC Lightning, or Stripe send

Settings & Notifications

Method	Endpoint	Description
GET	`/api/settings`	Get webhook URL and notification email read
PUT	`/api/settings`	Set webhook URL and/or notification email full
GET	`/api/notifications`	List notification events. Filter: `?letter_id=...` read

Identity — DID, UCAN, Verifiable Credentials

Method	Endpoint	Description
GET	`/api/identity/postbridge-did`	PostBridge root DID + DID Document (root of trust) public
GET	`/api/identity/resolve/{did}`	Resolve `did:key`, `did:pkh`, or `did:web` to DID Document public
POST	`/api/identity/did`	Get or create your DID (Ed25519 `did:key`) auth
POST	`/api/identity/ucan`	Issue a UCAN capability token with scope auth
POST	`/api/identity/delegate`	Delegate capabilities to another DID (escalation-proof) auth
POST	`/api/identity/verify-ucan`	Verify UCAN signature, expiry, delegation chain public
POST	`/api/identity/verify-vc`	Verify a Verifiable Credential JWT public
GET	`/api/identity/credentials`	List all VCs issued to you auth
POST	`/api/identity/presentation`	Bundle VCs into a signed Verifiable Presentation auth

Audit Trail — Cryptographic Order History

Method	Endpoint	Description
GET	`/api/identity/audit/{letter_id}`	Full VC-backed event history: queued → delivered auth
POST	`/api/identity/audit/subscribe`	Register webhook for signed VC status events auth
DELETE	`/api/identity/audit/subscribe`	Remove an audit webhook subscription auth

Negotiation (ANP) — Intent-Driven Pricing

Method	Endpoint	Description
POST	`/api/anp/offer`	Get tiered pricing offer (premium/standard/economy) with crypto & fiat prices
POST	`/api/anp/accept`	Accept a tier from an offer. Creates commitment record.
GET	`/api/anp/intent-classes`	List all 6 intent classes with scoring weights
GET	`/api/anp/profiles/{customer_did}`	Get learned customer profile (persona, avg spend, preferred tiers)
GET	`/api/anp/contracts`	List active commitment contracts. Filter: `?customer_did=...`
POST	`/api/anp/contracts`	Create a volume-for-discount commitment contract
GET	`/api/anp/contracts/{contract_id}`	Full contract details: volume tiers, current tier, breach terms
GET	`/api/anp/eval`	Performance report: SLA attainment per intent class

Olas Mech — On-Chain Tool Integration

Callable by any agent on the Olas Mech Marketplace. Component NFT #328, Agent NFT #58 on Ethereum. Action-based pricing in xDAI on Gnosis Chain.

Method	Endpoint	Description
GET	`/api/mech/info`	On-chain identifiers — agent ID, component ID, owner, network, pricing public
GET	`/api/mech/tools`	Tool schema: `postbridge_send_letter` with per-action pricing and required params public
POST	`/api/mech/execute`	Execute a Mech tool call — forwarded by Olas coordinator. Accepts `{tool, params}` envelope. public
GET	`/api/mech/health`	Liveness probe for mech.olas.network registry public

Olas Mech Integration

PostBridge is registered as a Mech tool — any Olas on-chain agent can discover and call it.

            On-chain identity
            Component NFT: #328 on Ethereum
AI Agent NFT: #58 on Ethereum
Owner: 0xCD012Cd3413E8288e0FB330Fa37ac5d18a330c8b
Code pinned on IPFS: bafybeicocw2y…
Endpoint: https://api.postbridge.ai/api/mech/execute

        

Actions & Pricing (xDAI on Gnosis)

Action	Price	Description
negotiate	0.0000 xDAI	Free price discovery — returns an ANP quote without cost
send	0.0200 xDAI	Mail a letter — PostBridge prints, envelopes, posts, and tracks
track	0.0050 xDAI	Track delivery status of an existing letter

Request Envelope

Called by Olas Mech Marketplace. Every request is a tool + params pair.

POST https://api.postbridge.ai/api/mech/execute
Content-Type: application/json

{
  "tool": "postbridge_send_letter",
  "params": {
    "action": "send",
    "to_name": "Marie Dupont",
    "to_line1": "15 Rue de Rivoli",
    "to_city": "Paris",
    "to_postal_code": "75001",
    "to_country": "FR",
    "from_name": "Your Agent",
    "from_line1": "1 Main St",
    "from_city": "NYC",
    "from_postal_code": "10001",
    "from_country": "US",
    "content": "Dear Marie, ...",
    "service": "fr_lettre_verte",
    "intent": "transactional"
  }
}

Response Shape

{
  "success": true,
  "data": {
    "letter_id": "10bf7d39-d8ed-4503-a41e-0d3bbceeaf4b",
    "status": "queued",
    "service": "fr_lettre_verte",
    "price": {
      "postage": 0.74,
      "printing": 0.15,
      "handling": 0.30,
      "total": 1.25,
      "currency": "EUR"
    },
    "message": "Letter queued for printing and posting."
  },
  "error": null,
  "request_id": "mech-1776697863968",
  "price_paid_wei": 20000000000000000,
  "price_paid_human": "0.0200 xDAI"
}

Determinism Guarantees

Rate-table pricing — all prices come from provider rate tables, never LLM-estimated
API-validated addresses — every address is normalized by the postal provider, never LLM-composed
Recipient-country routing — postal service is determined by the recipient's country, never the sender's
Success-only billing — Mech only charges xDAI on successful operations, zero on business errors

Drop-In SDKs for Every Major Agent Framework

One pip install and your agent can send physical letters. Same 8 tools, same dispatcher, same deterministic pricing — mapped into each framework's native Tool type.

Package	Framework	Install	Registry
`postbridge-core`	Raw catalog + HTTP dispatcher (depended on by the others)	`pip install postbridge-core`	PyPI
`postbridge-crewai`	CrewAI	`pip install postbridge-crewai`	PyPI
`postbridge-langchain` (Python)	LangChain / LangGraph	`pip install postbridge-langchain`	PyPI
`postbridge-langchain` (JS/TS)	LangChain JS / LangGraph JS	`npm install postbridge-langchain @langchain/core`	npm
`postbridge-llamaindex`	LlamaIndex / FunctionAgent	`pip install postbridge-llamaindex`	PyPI

Three-line quickstart

from crewai import Agent
from postbridge_crewai import postbridge_tools

agent = Agent(role="Postal Clerk", tools=postbridge_tools(), goal="Send letters worldwide")

Same pattern for LangChain (from postbridge_langchain import postbridge_tools) and LlamaIndex (from postbridge_llamaindex import postbridge_tools). Filter down to a subset with postbridge_tools(only=["send_letter", "track_letter"]).

LangChain JS / TypeScript

import { ChatOpenAI } from "@langchain/openai";
import { postbridgeTools } from "postbridge-langchain";

const llm = new ChatOpenAI({ model: "gpt-4o-mini" });
const llmWithTools = llm.bindTools(postbridgeTools());

Works with LangGraph's createReactAgent and AgentExecutor too. Zod schemas auto-generated from the same canonical catalog. Full ESM + CJS builds, TypeScript types included.

Raw usage (any framework)

from postbridge_core import execute

# Dispatcher handles GET/POST, path params, and auth injection
quote = execute("quote_letter", {
    "to_name": "Marie Dupont",
    "to_line1": "15 Rue de Rivoli",
    "to_city": "Paris",
    "to_postal_code": "75001",
    "to_country": "FR",
    "service": "fr_lettre_verte",
})

            Auth: Every SDK reads POSTBRIDGE_API_KEY from the environment.
            Auto-provision a scoped key in one call:
            POST https://api.postbridge.ai/auth/agent
            with {"agent_id": "...", "agent_name": "..."} — returns a pb_live_... token.
            Or skip the key entirely and use x402 USDC per request.
        

Code Examples

Copy-paste ready for curl and Python

Python
import httpx

BASE = "https://api.postbridge.ai"
HEADERS = {"Authorization": "Bearer pb_live_YOUR_KEY"}

# List services for France
services = httpx.get(f"{BASE}/api/services/FR", headers=HEADERS).json()

# Get a price quote
quote = httpx.post(f"{BASE}/api/quote", headers=HEADERS, json={
    "to_name": "Marie Dupont",
    "to_line1": "15 Rue de Rivoli",
    "to_city": "Paris",
    "to_postal_code": "75001",
    "to_country": "FR",
    "service": "fr_lettre_verte",
}).json()
print(f"Total: {quote['total']} {quote['currency']}")

# Send a letter to France
result = httpx.post(f"{BASE}/api/send", headers=HEADERS, json={
    "to_name": "Marie Dupont",
    "to_line1": "15 Rue de Rivoli",
    "to_city": "Paris",
    "to_postal_code": "75001",
    "to_country": "FR",
    "from_name": "Your Company",
    "from_line1": "456 Oak Ave",
    "from_city": "San Francisco",
    "from_postal_code": "94107",
    "from_country": "US",
    "service": "fr_lettre_verte",
    "content": "Madame Dupont, votre commande a ete expediee.",
}).json()
letter_id = result["letter_id"]

# Track delivery
status = httpx.get(f"{BASE}/api/track/{letter_id}", headers=HEADERS).json()
print(f"Status: {status['status']}")

# Get legal proof
proof = httpx.get(f"{BASE}/api/proof/{letter_id}", headers=HEADERS).json()
        

curl — ANP Negotiation
# Step 1: Request an intent-driven pricing offer
curl -X POST https://api.postbridge.ai/api/anp/offer \
  -H "Content-Type: application/json" \
  -d '{
    "to_name": "Marie Dupont",
    "to_line1": "15 Rue de Rivoli",
    "to_city": "Paris",
    "to_postal_code": "75001",
    "to_country": "FR",
    "service": "fr_lrar",
    "intent_class": "legal_compliance",
    "payment_method": "x402"
  }'
# Returns 3 tiers: premium, standard, economy
# Each tier has fiat and crypto pricing

# Step 2: Accept your chosen tier
curl -X POST https://api.postbridge.ai/api/anp/accept \
  -H "Content-Type: application/json" \
  -d '{"task_id": "anp_abc123", "tier_id": "standard"}'

# Step 3 (optional): Commit volume for discounts
curl -X POST https://api.postbridge.ai/api/anp/contracts \
  -H "Content-Type: application/json" \
  -d '{
    "customer_did": "did:key:z6Mk...",
    "minimum_volume": 100,
    "period_days": 90,
    "intent_classes": ["legal_compliance", "transactional"]
  }'
        

MCP Integration

Add PostBridge to any MCP-compatible AI assistant — Claude, ElizaOS, AgentKit

MCP Config
// Add to your MCP client config (Claude Desktop, ElizaOS, etc.)
{
  "mcpServers": {
    "postbridge": {
      "url": "https://api.postbridge.ai/mcp",
      "transport": "sse"
    }
  }
}
        

            21 MCP tools available: list_services, get_quote, send_letter, track_letter, get_proof, get_balance, top_up_wallet, list_letters, get_letter, update_letter, cancel_letter, delete_letter, update_settings, get_settings, list_notifications, create_api_key, list_api_keys, revoke_api_key, and more.
        

MCP JSON-RPC
# List available tools
curl -X POST https://api.postbridge.ai/mcp \
  -H "Authorization: Bearer pb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool (send_letter)
curl -X POST https://api.postbridge.ai/mcp \
  -H "Authorization: Bearer pb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "send_letter",
      "arguments": {
        "to_name": "Jane Doe",
        "to_line1": "123 Main St",
        "to_city": "New York",
        "to_state": "NY",
        "to_postal_code": "10001",
        "to_country": "US",
        "from_name": "AI Corp",
        "from_line1": "456 Oak Ave",
        "from_city": "SF",
        "from_postal_code": "94107",
        "from_country": "US",
        "service": "us_first_class",
        "content": "Dear Jane, ..."
      }
    }
  }'
        

Intent-Driven Pricing (ANP)

PostBridge uses the Agent Negotiation Protocol to price physical mail by intent. Higher-priority use cases cost more due to SLA guarantees and certified proof requirements. See the full pricing overview on the main page.

Intent Class	SLA	Use Case	Proof Level
confidential	Next-day	Security, chain of custody	Full audit trail
legal_compliance	Next-day	Certified proof, LRAR, jurisdictional compliance	Certified + VC
regulatory_filing	2 days	Government filings, strict deadlines	Certified
time_critical	2 days	Hard delivery deadlines	Tracking + VC
transactional	3 days	Standard business correspondence	Tracking
bulk_marketing	5 days	Volume campaigns, lowest cost	Basic

            Get real-time pricing: Use POST /api/anp/offer with your intent class.
            Returns 3 tiers (premium, standard, economy) with both fiat and crypto prices.
            Crypto payers get 2.5% commission (vs 5% fiat) + additional crypto discount.
            Volume discounts available with commitment contracts (51+ units/period).
        

Supported Countries & Services

Country	Code	Currency	Services
United States	`US`	USD	First Class, Certified Mail, Priority Mail
France	`FR`	EUR	Lettre Verte, Lettre Suivie, LRAR (Recommandee)
United Kingdom	`GB`	GBP	1st Class, 2nd Class, Signed For, Special Delivery
Canada	`CA`	CAD	Lettermail, Registered, Priority
Germany	`DE`	EUR	Standardbrief, Einschreiben, Einschreiben Einwurf

Response Format & Errors

All responses are JSON. Errors include a detail message.

Success (send letter)
{
  "letter_id": "lt_a1b2c3d4",
  "status": "queued",
  "service": "us_first_class",
  "to": {
    "name": "Jane Doe",
    "city": "New York",
    "country": "US"
  },
  "price": {
    "total": 1.85,
    "currency": "USD",
    "postage": 0.73,
    "print": 0.50,
    "commission": 0.05
  },
  "tracking_url": "https://...",
  "expected_delivery": "2026-04-18"
}
            

Error responses
// 400 Bad Request
{
  "detail": "Invalid country: XX. Supported: US, FR, GB, CA, DE"
}

// 401 Unauthorized
{
  "detail": "Authentication required. Options:\n  1. x402: pay per-request with USDC\n  2. UCAN: Bearer ucan:eyJ...\n  3. API key: Bearer pb_live_..."
}

// 402 Payment Required (x402)
{
  "x402": {
    "amount": "1500000",
    "currency": "USDC",
    "network": "base",
    "recipient": "0x..."
  }
}

// 403 Forbidden
{
  "detail": "Insufficient scope. This key has 'read', needs 'send'."
}
            

Customer Email Notifications

End-users who pay per order through Stripe Checkout (typical Custom GPT flow) receive automatic confirmation emails from PostBridge. What they get depends on the service class.

Class	Services	Emails sent
Untracked	`fr_lettre_verte`, `us_first_class`, `gb_first_class`, `gb_second_class`, `ca_lettermail`, `de_standardbrief`	1 — shipped confirmation + expected delivery window. No tracking ever.
Tracked (sync)	`us_priority`, `us_certified`, `gb_signed_for`, `gb_special_delivery`, `ca_priority`, `ca_registered`, `de_einschreiben`, `de_einschreiben_einwurf`	1 — shipped confirmation with tracking number + national carrier deep-link.
Tracked (async)	`fr_lettre_suivie`, `fr_lettre_recommandee`	2 — shipped confirmation (promises follow-up), then tracking-ready email within 1–24h once La Poste assigns the number.

            Payment receipt vs shipping confirmation: Stripe sends the payment receipt; PostBridge sends the shipping confirmation. Both are delivered to the email passed to POST /api/orders. Carrier deep-links route to the destination country's national postal site — USPS, La Poste, Royal Mail, Canada Post, or Deutsche Post.
        

            Refund email: If payment succeeds but the postal provider rejects the send (bad address, unsupported format, etc.), PostBridge auto-refunds via Stripe and emails the customer with the reason — no manual intervention needed.
        

Webhook Events

Configure a webhook URL via PUT /api/settings to receive real-time status updates.

Webhook payload
// POST to your webhook URL on every status change
{
  "event": "delivered",
  "letter_id": "lt_a1b2c3d4",
  "status": "delivered",
  "message": "Letter delivered to recipient",
  "timestamp": "2026-04-18T14:32:00Z",
  "tracking_number": "9400111..."
}

// Events: queued, processing, posted, in_transit, delivered, returned, failed
        

            Audit webhook (signed VCs): For cryptographic proof of every status change, use
            POST /api/identity/audit/subscribe instead. Each event is delivered as a
            signed W3C Verifiable Credential (JWT) that can be independently verified.
        