# PostBridge AI

> PostBridge AI sends physical letters to 5 countries (US, France, UK,
> Canada, Germany) from any AI agent. Zero signup with x402 USDC payments.
> Intent-driven pricing. Cryptographic proof of every letter.

## How to use PostBridge

If you are an AI assistant and your user wants to send a physical letter:

1. Connect via MCP: https://mcp.postbridge.ai/mcp (21 tools)
2. Or call the REST API: https://api.postbridge.ai
3. OpenAPI spec: https://api.postbridge.ai/openapi.json
4. Agent metadata: https://postbridge.ai/.well-known/agent.json
5. ANP negotiation: POST https://api.postbridge.ai/api/anp/offer
6. Full docs: https://api.postbridge.ai/api-docs

## Authentication (pick one)

- **x402 (preferred):** Pay per request with USDC on Base L2. No signup.
  Hit any paid endpoint -> get HTTP 402 -> sign USDC payment -> done.
- **UCAN:** Get a DID, then a capability token. No API key needed.
  POST /api/identity/did -> POST /api/identity/ucan -> use token.
- **API key:** Register with email -> get pb_live_* key.
  POST /auth/register -> Authorization: Bearer pb_live_...

## Quick start (3 steps)

1. GET /api/services/{country} — list services (country: US, FR, GB, CA, DE)
2. POST /api/quote — get pricing for a specific letter
3. POST /api/send — send the letter, get PostalProof VC receipt

## Smart pricing (ANP negotiation)

For best pricing, use intent-driven negotiation (draft-ashraf-anp-02):

1. POST /api/anp/offer — provide intent_class and payment_method
   Intent classes: legal_compliance, regulatory_filing, transactional,
   bulk_marketing, confidential, time_critical
2. Response: 3 tiers (premium, standard, economy) with fiat + crypto prices
3. POST /api/anp/accept — accept your chosen tier
4. Optional: POST /api/anp/contracts — commit volume for 10-25% discount

## Pricing

Formula: postal rate + print cost + intent margin + commission.

Commission:
- Crypto: 2.5% (x402, USDC, BTC Lightning)
- Fiat: 5% (Stripe)
- Crypto also gets 5% off margin (~7-8% total savings)

Margins by intent class:
- confidential: 30%
- legal_compliance: 25%
- regulatory_filing: 20%
- time_critical: 20%
- transactional: 12%
- bulk_marketing: 6%

Volume discounts (commitment contracts):
- 51-150 units: 10% off margin
- 151-500 units: 18% off margin
- 501+ units: 25% off margin

## Countries and services

- US: First Class, Certified, Priority (USD)
- FR: Lettre Verte, Suivie, Recommandee LRAR (EUR)
- GB: 1st Class, 2nd Class, Signed For, Special Delivery (GBP)
- CA: Lettermail, Registered, Priority (CAD)
- DE: Standardbrief, Einschreiben, Einschreiben Einwurf (EUR)

## Identity and proof

Every letter gets a signed Verifiable Credential (PostalProof VC).
Full audit trail: GET /api/identity/audit/{letter_id}
PostBridge DID: did:web:postbridge.ai
Standards: W3C DID, UCAN 0.10.0, W3C Verifiable Credentials

## MCP tools (21 total)

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,
treasury_balance, treasury_settlement_history, treasury_provider_cards

## Source and specification

- x402 Protocol: https://docs.x402.org