Agent Ticketing, Listing, And Settlement
ATLAS is an open protocol that makes every event on the internet discoverable, bookable, and settleable by software agents. On the guest side, AI agents find and purchase tickets through a standard HTTP 402 flow. On the organizer side, the same agent infrastructure creates events, manages guest relationships through decentralized CRM, and reaches new audiences through a protocol-native ad-network.
Event data is stored on IPFS for permanence. Settlement occurs in USDC on any supported EVM chain. The protocol charges a flat 2% fee and returns value to participants through USDC cashback.
atlas-protocol/
├── specs/ # Protocol specifications (source of truth)
├── whitepaper/ # Whitepaper + supporting research
├── guides/ # Integration + partnership guides
├── packages/ # TypeScript SDK packages (pnpm workspace)
│ ├── types/ # Shared types
│ ├── agent-tools/ # Agent SDK (LangChain + MCP)
│ └── server-sdk/ # Reference server implementation
├── contracts/ # Solidity contracts (Foundry)
└── examples/ # Integration quickstarts
pnpm install
pnpm build
pnpm testNode >=24 and pnpm >=9 are required. See CONTRIBUTING.md for the full setup, package conventions, and spec-change process.
| Document | Description |
|---|---|
| Whitepaper | The complete protocol specification. Problem, vision, design principles, protocol overview, three-layer architecture, settlement, economics, network effects, organizer intelligence layer, progressive decentralization. |
| Architecture | System architecture. IPFS data layer, chain-agnostic settlement, registry federation, XMTP CRM, ad-network, smart contracts, security, infrastructure, data flow diagrams. |
| Market Research | $1T+ events industry analysis. TAM/SAM/SOM, experience economy trends, Gen Z/Gen X behavior, AI agent opportunity, platform fragmentation, competitive landscape. Cited sources. |
| Spec | Description |
|---|---|
| 01 Protocol Spec | Core protocol: well-known endpoints, registry API, HTTP 402 purchase flow, W3C receipt format, versioning, error codes. |
| 02 Schemas | Every JSON schema: AtlasEvent, AtlasTicketType, AtlasManifest, AtlasPurchaseChallenge, AtlasCredential, AtlasCampaign, AtlasMessage. |
| 03 Settlement | Chain-agnostic settlement: Base, MegaETH, World Chain, Arbitrum, Ethereum. USDC routing, MPP payment integration, gas optimization. |
| 04 Smart Contracts | Five Solidity contracts: FeeRouter, AtlasTicket (ERC-721), RewardLedger, RegistryPointer, PromotionSettlement. Function signatures, access control, upgrade paths. |
| 05 IPFS Data Layer | IPFS as the permanence layer: publishing pipeline, CID generation, cluster operations, receipt storage, fallback resolution. |
| 06 XMTP CRM | Decentralized CRM on XMTP: channel establishment, data model, key management, segment queries, messaging, privacy, portability. |
| 07 Ad-Network | Protocol-native advertising: campaign model, pay-per-sale bidding, agent relevance, settlement (60/30/10 split), economics vs Meta/Google. |
| 08 Agent Ecosystem | Two-sided agent layer: 9 MCP tools, lemonade-cli reference, @atlasprotocol/client SDK, @atlasprotocol/server-sdk, agent identity, Space as Platform. |
| 09 Fee Economics | 2% protocol fee, reward tiers, referral program, promotion revenue, token phases (LMC, $LEMON), fee comparison tables. |
| 10 Progressive Decentralization | Five-stage trust migration: on-chain payments, fee splits, tickets, rewards, registry. Governance alignment, migration mechanics. |
| 11 Governance | Four governance phases: Lemonade stewardship, advisory board, steering committee, ATLAS Foundation. Voting mechanics, emergency procedures. |
| 12 Security & Privacy | TLS 1.3, API authentication, purchase security, smart contract security, data privacy (AES-256-GCM), GDPR/CCPA compliance. |
| Guide | Description |
|---|---|
| Connector Architecture | How ATLAS imports events from external platforms: OAuth connectors, sync architecture, event normalization, IPFS publishing. |
| Organizer Experience | The complete organizer journey: onboarding, Space as Platform, AI agents, XMTP CRM, ad-network promotion, rewards. |
| Partnership Playbook | Bottom-up and top-down partnership strategy: platform tiers, agent ecosystem, ad-network as partnership lever. |
| Roadmap | Strategic roadmap tied to GMV milestones: Phase 0 (launch) through Phase 3 (foundation and full decentralization). |
AGENT LAYER Guest Agents (discover, book) + Organizer Agents (create, CRM, promote)
COMMUNICATION XMTP (E2E encrypted organizer-guest messaging)
AD-NETWORK Promotion bids + Relevance filtering + Pay-per-sale
REGISTRY Federated search + Well-known endpoints + OAuth imports
DATA IPFS (permanent, content-addressed event storage)
SETTLEMENT Base + MegaETH + World Chain + Arbitrum + Ethereum L1
CONTRACTS FeeRouter + AtlasTicket + RewardLedger + RegistryPointer + PromotionSettlement
Any event platform can install a few packages and accept agent purchases over both rails out of the box: discoverable from any agent surface (Claude / ChatGPT / Gemini / your own), settled either on-chain (multi-L2 USDC via x402) or in fiat (Stripe SPT, USDC out), with the buyer's W3C VC receipt pinned to IPFS.
# Server-side primitives + IPFS pinners (peer dep — only needed if you opt
# into receipt auto-pinning):
pnpm add @atlasprotocol/server-sdk @atlasprotocol/ipfs viem hono
# Optional, only when accepting fiat:
pnpm add stripe- Copy the reference server.
examples/dual-protocol-server/is a complete Hono service with all four ATLAS endpoints (/.well-known/atlas.json,/atlas/v1/search,/atlas/v1/events/:id,/atlas/v1/events/:id/purchase). Use it as your starter: copy the four route handlers into your existing service and swapsrc/data.tsfor whatever wraps your event database. - Set environment variables. See
examples/dual-protocol-server/.env.examplefor the complete list — at minimumORGANIZER_ADDRESS,STRIPE_SECRET_KEY(if accepting fiat), and the optional integration block (ATLAS_TICKET_ADDRESS,REWARD_LEDGER_ADDRESS,WALLET_PRIVATE_KEY,RPC_URL,PINATA_JWT) when you're ready to wire the on-chain mint + reward + receipt-pinning steps. - Deploy contracts on your settlement chain. Each chain has its own runbook in
contracts/deploy/— required env vars, canonical stablecoin contract,forge scriptinvocation, post-deploy verification command. The proxies write back intodeployments.jsonwhich the SDK accessors then read. - Wire the endpoints. The example performs the full composition — issue a 402 with
generateMppChallenge, verify the retry credential withverifyPayment/verifyStripePayment, mint the AtlasTicket NFT withbuildMintTicketTx, credit the organizer reward withbuildRecordRewardTx, and pin the W3C VC receipt withgenerateReceipt({ ..., pinner }). Seeexamples/dual-protocol-server/src/index.tsfor the end-to-end flow. - (Agent side.) For the agent side of the same flow, see
examples/agent-dual-client/— it pays the 402 with x402 if a wallet is configured and falls back to stripe-mpp if a Stripe key is.
Breaking change in 0.4.0.
generateReceiptis nowasyncand returns{ receipt, cid? }. The optionalpinnerparameter is the new pluggable IPFS pinner (@atlasprotocol/ipfs). Migrate by addingawaitand destructuring the result.
The cross-cutting invariants (paymentId carries unchanged through verify → mint → reward → receipt; replays are rejected; pinner is called exactly once) are exercised by packages/server-sdk/src/__tests__/end-to-end.test.ts, which composes the same SDK primitives the example server uses.
Phase 5.3 introduces an operator-side path for platforms that don't want to run their own IPFS pinner, treasury hot wallet, or RPC clients. The ATLAS registry deployment runs the pinner, holds the settlement funds, and broadcasts the on-chain calls; platforms call four HTTP endpoints and get back a confirmed result.
The registry exposes four /atlas/v1/* endpoints (full request/response shapes in 01-whitepaper/docs/01-PROTOCOL-SPEC.md):
| Endpoint | Purpose | Spec |
|---|---|---|
POST /atlas/v1/receipts/pin |
Pin a receipt's proof-of-issuance to IPFS, return its URN + CID. | 05-IPFS-DATA-LAYER §6 |
POST /atlas/v1/receipts/verify |
Re-canonicalise + hash a receipt and confirm it matches a pinned proof. Accepts either the full receipt or a { urn, cid } lookup. |
05-IPFS-DATA-LAYER §6 |
POST /atlas/v1/settlements/settle |
Execute a FeeRouter.settle() call from the ATLAS treasury hot wallet on the platform's behalf. Idempotent on paymentId. |
03-SETTLEMENT-SPEC §10 |
POST /atlas/v1/rewards/record |
Accrue organizer / attendee / referral rewards via RewardLedger.recordRewards() on Base (the canonical reward chain). Recipients claim directly via claim() / claimTo(). |
03-SETTLEMENT-SPEC §10 |
The SDK ships a typed client wrapping all four:
pnpm add @atlasprotocol/server-sdk@^0.7.0import { createAtlasManagedClient } from '@atlasprotocol/server-sdk';
const atlas = createAtlasManagedClient({
baseUrl: 'https://registry.atlas-protocol.org',
platformAuthToken: process.env.ATLAS_PLATFORM_TOKEN, // optional
});
// After verifying the buyer's payment proof, hand settlement to ATLAS:
const settled = await atlas.settle({
platformDomain: 'atlas.bjc.events',
chain: 'base',
organizer: organizerAddress,
totalAmount: 50_000_000n, // 50 USDC, 6 decimals
paymentId: holdId, // doubles as idempotency key
platformFees: [{ recipient: protocolTreasury, amount: 250_000n }],
});
// Record rewards (Base canonical chain):
await atlas.recordRewards({
platformDomain: 'atlas.bjc.events',
paymentId: holdId,
recipients: [
{ recipient: organizerAddress, kind: 'organizer', amount: 600_000n },
{ recipient: attendeeAddress, kind: 'attendee', amount: 200_000n },
],
});
// Pin + verify the W3C VC receipt:
const { urn, cid } = await atlas.pinReceipt(receipt);
const { valid } = await atlas.verifyReceipt({ urn, cid });See packages/server-sdk/README.md for the full client API and packages/server-sdk/src/__tests__/atlas-managed-integration.test.ts for an end-to-end mocked-fetch lifecycle.
Auth model. Receipt endpoints (pin, verify) identify the calling platform from the receipt's URN domain — the registry resolves the URN against registered_platforms and verifies the caller. Settlement endpoints (settle, recordRewards) take the platform identity in the request body via platform_domain and authenticate via the optional Authorization: Bearer <platformAuthToken> header.
Sovereignty is preserved. Platforms that want to keep control of their own treasury and signing keys can still call the contracts directly — buildSettleTx and buildRecordRewardTx continue to be supported alongside the managed path. The trade-off is operational: managed mode shifts the burden of key custody, RPC reliability, and gas funding to the registry operator, at the cost of trusting that operator with broadcast timing.
For agent developers:
npm install @atlasprotocol/agent-tools @atlasprotocol/mppFor platform integrators:
npm install @atlasprotocol/server-sdk @atlasprotocol/mppFor organizers and builders:
# Install the CLI
npm install -g lemonade-cli
# Create a space (= create an event platform)
lemonade space create --name "Brooklyn Jazz Collective" --domain bjc.events --type music
# Create an event
lemonade event create --space bjc_abc123 --title "Late Night Jazz" --date 2026-04-15T21:00 --price 25.00Each supported settlement chain has its own deploy runbook in contracts/deploy/ — required env vars, canonical stablecoin contract, forge script invocation, post-deploy verification command. Production-ready: Base, Optimism, Arbitrum, World Chain. Experimental: MegaETH (USDM until Circle ships canonical USDC). Placeholder: Tempo (pending public mainnet).
Phase 5 status (May 2026). FeeRouter v2, AtlasTicket v2, and RewardLedger v2 are all spec-complete. No proxies are deployed yet on any chain — every entry in
deployments.jsonisnull. Per-chain deploy runbooks live incontracts/deploy/(Base, Optimism, Arbitrum, Polygon, zkSync, World Chain, MegaETH, Tempo). RewardLedger v1 ships canonical-chain only — Base mainnet (base_usdc) and Base Sepolia (base_sepolia_usdc); multi-chain RewardLedger is Phase 7+ perspecs/10-PROGRESSIVE-DECENTRALIZATION.md.
deployments.json at the repo root is the canonical registry of deployed ATLAS contracts — currently feeRouter (Stage 1 payment settlement), atlasTicket (Stage 2 ERC-721 NFT tickets), and rewardLedger (Stage 3 organizer / attendee / referral reward accrual + claim ledger). For each contract family it records the CREATE2 salt for the implementation contract (deterministic across chains) and the per-chain UUPS proxy addresses (per-chain by design — chain-specific init params produce per-chain digests). Every chain present in the SDK's CHAIN_SPECS has an entry in feeRouter.proxies and atlasTicket.proxies, including testnet variants; entries are null until that chain has a real deployment. rewardLedger.proxies covers only the canonical Base + Base Sepolia slots in v1.
The SDK exposes typed accessors over this registry:
import {
getAtlasTicketAddress,
getAtlasTicketImplementation,
getFeeRouterAddress,
getFeeRouterImplementation,
getRewardLedgerAddress,
getRewardLedgerImplementation,
listDeployedChains,
listKnownChains,
} from "@atlasprotocol/server-sdk";
getFeeRouterAddress("base_usdc"); // → "0x..." once deployed, undefined otherwise
getFeeRouterImplementation(); // → CREATE2 implementation address
getAtlasTicketAddress("base_usdc"); // → AtlasTicket proxy on Base, undefined otherwise
getAtlasTicketImplementation(); // → AtlasTicket CREATE2 implementation address
getRewardLedgerAddress("base_usdc"); // → RewardLedger proxy on Base, undefined otherwise
getRewardLedgerImplementation(); // → RewardLedger CREATE2 implementation address
listDeployedChains(); // → chain slugs that have a non-null FeeRouter proxy
listKnownChains(); // → every chain slug in deployments.jsonWhen adding a new chain, update CHAIN_SPECS and feeRouter.proxies + atlasTicket.proxies + rewardLedger.proxies in deployments.json together — the SDK's parity test fails if any side has an orphan key. See contracts/MULTICHAIN.md for the deploy procedure and CREATE2 derivation details.
| Chain | Type | Tx Fee | Block Time | USDC |
|---|---|---|---|---|
| Base | OP Stack L2 | ~$0.01 | ~2 sec | Native |
| MegaETH | EVM L2 | <$0.01 | ~10 ms | Bridge |
| World Chain | OP Stack L2 | ~$0.01-0.03 | ~2 sec | Bridge |
| Arbitrum | Nitro L2 | ~$0.01 | ~0.25 sec | Native |
| Ethereum | Mainnet | $2-50 | ~12 sec | Native |
ATLAS is an open protocol. The specification is public. Contributions are welcome via pull request.
For protocol changes, submit an RFC as a GitHub issue. The governance process (see Governance Spec) determines how changes are reviewed and approved.
ATLAS Protocol is created by Lemonade. The protocol specification is open source.