# Overview ### 1. What is Unibase? Unibase is a high-performance decentralized AI memory layer. It equips AI agents with **long-term memory** and **cross-platform interoperability**, enabling them to **remember**, **collaborate**, and **self-evolve** autonomously. Unibase is building the foundation for the **Open Agent Internet** — a modular, verifiable, and composable AI agent ecosystem onchain. ### 2. Project Status * ✅ **Live** on **BNBChain Mainnet** * ✅ SDKs, Docs, and Explorer fully released * ✅ Integrated with **MCP, ElizaOS, Virtuals, and Swarms** * ✅ 1,000+ agent interactions recorded via Unibase SDK * ✅ BitAgent, TradingFlow, TwinX, Beeper online See [Status & Maturity](/unibase-docs/readme/status) for per-module status (live / testnet / in audit). ### 3. Choose Your Path | I want to... | Start here | | ------------------------------- | ------------------------------------------------------------------- | | **Add memory to my Agent** | [Membase Quick Start](/unibase-docs/get-started/membase-quickstart) | | **Build multi-agent systems** | [AIP Quick Start](/unibase-docs/get-started/aip-quickstart) | | **Enable agent payments** | [Unibase Pay Quick Start](/unibase-docs/get-started/pay-quickstart) | | **Run storage/validator nodes** | [Unibase DA Quick Start](/unibase-docs/get-started/da-quickstart) | | **Capture & reuse my AI chats** | [Unibase Memory](/unibase-docs/unibase-memory/getting-started) | *** ### 4. Problems Solved | Problem | Unibase Solution | | ------------------- | ------------------------------------------------ | | No long-term memory | Membase — persistent, verifiable storage | | Isolated agents | AIP — cross-platform identity & interoperability | | Data sovereignty | Decentralized storage, on-chain verification | ### 5. Core Modules | Module | One-line | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Membase** | Agent memory & collaboration SDK — wallet-owned encrypted memory, on-device recall, agent-direct cooperation, on-chain settlement. SDK / MCP / skill. | | **AIP Protocol** | Agent interoperability — identity, permissioning, shared memory. ERC-8004 & x402. | | **Unibase Pay** | x402 on BNB Chain — agents search, pay, access. Privy wallet, micropayments. | | **Unibase DA** | Data availability — erasure-coded, ZK-verified, honest-one fraud proofs, EB+ capacity. | | **Unibase Memory** | Chrome extension — capture, organize & reuse ChatGPT/Claude/Gemini chats. Encrypted, owned, verifiable. | > **Membase vs Unibase Memory:** **Membase** is the developer **SDK** for building agents with memory & collaboration. **Unibase Memory** is the consumer **Chrome extension** for capturing and reusing your own AI chats (built on the same stack). ### 6. Ecosystem BitAgent · TwinX · TradingFlow · MCP, ElizaOS, Virtuals, Swarms # Architecture
Unibase layered architecture: Application, Middleware, Core, Infrastructure
This layered architecture reflects the modular and decentralized nature of the Unibase ecosystem, where each layer builds upon the previous one to create a secure, scalable, and interoperable framework for AI agents. ### 1. Application Layer The top layer consists of AI agents that users interact with directly: * **Trader Agent** — Autonomous trading on BNBChain * **Personal Agent** — Personalized assistance based on user data * **Chess Agent** — Multi-agent games with decentralized memory ### 2. Middleware The **Middleware** layer bridges the Application and Core layers: * **Memory & Recall** — persistent, owned memory and recall-ready retrieval for agents across sessions (Membase) * **Knowledge** — shared, decentralized knowledge accessible to agent groups * **Discovery & Config** — agent/tool capability registration and lookup (AIP) ### 3. Core Layer The **Core Layer** includes: * **AIP** — Communication standards and interaction protocols between agents * **Membase** — Decentralized memory, identity, and cooperation layer * **Unibase DA** — Data availability and storage layer * **Unibase Pay** — x402 payment facilitator for agent commerce ### 4. Infrastructure The **Infrastructure Layer** provides: * **Blockchain** — Identity verification and transaction security * **Storage** — Distributed storage for data and models * **LLM API** — Integration with large language models *** ### How the modules compose The four core modules are independent but composable — each owns one concern, and an agent uses whichever it needs: ``` Membase ── memory, identity (wallet), cooperation │ uses ▲ │ stores verifiable data on │ ▼ AIP ──┤ Unibase DA ── decentralized, erasure-coded storage (interop, │ ERC-8004)│ settles / pays via │ ▼ └─ Unibase Pay ── x402 micropayments between agents ``` * **AIP** builds on **Membase** for agent identity and shared memory, and uses **Unibase Pay** (x402) to charge for agent calls. * **Membase** persists verifiable memory on **Unibase DA** and can meter usage through on-chain settlement. * Each module is usable on its own — you don't need the whole stack to add memory, payments, or storage. ### When to use which | You want to… | Use | | -------------------------------------------------------------- | ------------------------------------- | | Give an agent long-term, owned memory + recall | **Membase** | | Let agents from different vendors discover & call each other | **AIP** | | Charge / pay per agent request or API call | **Unibase Pay** | | Store large data with on-chain verifiability | **Unibase DA** | | Capture & reuse your own ChatGPT/Claude/Gemini chats (no code) | **Unibase Memory** (Chrome extension) | # Core Concepts ### 1. Membase: Agent Memory & Collaboration The foundational memory layer of Unibase. Each agent owns a wallet, signs every write, and runs against a public Hub directly — no operator in the trust path: * **Wallet-rooted identity** — the agent's Ethereum address is its identity; the key signs every write and unlocks its memory. * **Owned, encrypted memory** — content-addressed storage plus on-device recall (distilled observations + retrieval); confidentiality via **domain** keys, not server ACLs. * **Agent-direct collaboration** — signed, hash-chained logs on the Hub let agents coordinate tasks with no central referee, replayable by any third party. * **On-chain settlement** — Hub usage metered off-chain and settled via ERC-8183. Membase supports **SDK**, **MCP**, and **skill** integration. ### 2. AIP (Agent Internet Protocol) AIP defines the communication standards and security protocols for Agent interactions: * **Standardized Workflows** — Message formats, communication protocols, and data structures for cross-Agent interoperability. * **Decentralized Authorization** — Cryptographic signature-based identity/authorization verification. * **Multi-layered Trust** — Decentralized identities, ZKPs, and flexible permission verification. AIP **extends A2A** for agent communication, with **ERC-8004** identity and **x402 + ERC-8183** payment & settlement. ### 3. Unibase Pay: Agent Payments & x402 Unibase Pay is the x402 facilitator on BNB Chain: * **x402 V2** — Verify, settle, monitor, payment gating, micropayments. * **EIP-3009 & Permit2** — All ERC20 tokens; gasless transfers. * **Privy Custodial Wallet** — Third-party wallet for agents; usable via MCP and skill. ### 4. Unibase DA: Decentralized Storage & Data Availability Unibase DA provides decentralized, persistent storage: * **Distributed Storage** — Reed-Solomon `(N,K)` erasure coding; any `K` of `N` shards reconstruct the data. * **On-chain Verifiability** — ZK-based **encoding** and **availability** proofs under an **honest-one** fraud-proof model (a single honest party forces correctness). * **Multi-EVM** — Settles on **Base** (primary), with **BSC** on the roadmap. * **High Performance** — 32–81 GB/s throughput, EB+ capacity, million-node scale. # Supported Networks > **Naming:** "BNB Chain" and "BSC" refer to the same network; we use **BNB Chain** in prose and **BSC + chain ID** in technical contexts. ### Membase | Network | Chain ID | Status | Explorer | | ----------------------- | -------- | ------ | --------------------------------------------------------------------------- | | BNB Chain (BSC) Mainnet | 56 | ✅ Live | [bscscan.com](https://bscscan.com/) | | BNB Chain (BSC) Testnet | 97 | ✅ Live | [testnet.bscscan.com](https://testnet.bscscan.com/) | | opBNB Testnet | 5611 | ✅ Live | [opbnb-testnet.bscscan.com](https://opbnb-testnet.bscscan.com/) | | OP Sepolia | 11155420 | ✅ Live | [sepolia-optimistic.etherscan.io](https://sepolia-optimistic.etherscan.io/) | ### AIP AIP runs on **Base and BSC** (mainnet and testnet). Default registration chain is BSC Testnet (97). | Network | Chain ID | Status | Explorer | | ----------------------- | -------- | ------ | ----------------------------------------------------- | | BNB Chain (BSC) Mainnet | 56 | ✅ Live | [bscscan.com](https://bscscan.com/) | | BNB Chain (BSC) Testnet | 97 | ✅ Live | [testnet.bscscan.com](https://testnet.bscscan.com/) | | Base Mainnet | 8453 | ✅ Live | [basescan.org](https://basescan.org/) | | Base Sepolia | 84532 | ✅ Live | [sepolia.basescan.org](https://sepolia.basescan.org/) | ### Unibase Pay | Network | Chain ID | Status | API | | ----------- | -------- | ------ | ---------------------------------------------------------- | | BSC Mainnet | 56 | ✅ Live | [api.x402.unibase.com/v2](https://api.x402.unibase.com/v2) | | BSC Testnet | 97 | ✅ Live | [api.x402.unibase.com/v2](https://api.x402.unibase.com/v2) | ### Unibase DA | Network | Chain ID | Status | Notes | | ---------------- | -------- | ---------------- | ----------------------------------------------------------------- | | Base Sepolia | 84532 | ✅ Live (testnet) | Current DA deployment (`CHAIN_TYPE=base-sepolia`) | | Base Mainnet | 8453 | 🔄 In audit | ZK verification contracts (primary L2 target) | | Ethereum Mainnet | 1 | 🗺️ Roadmap | ZK verification contracts (security anchor / ERC-8004 legitimacy) | > DA anchors **Ethereum + Base only**. BSC is an application-layer chain (Pay/AIP); DA does **not** deploy on BSC. ### Getting Tokens * **Mainnet**: Use BNB on BNBChain Mainnet for production. [bscscan.com](https://bscscan.com/) * **Testnet Faucet**: * Ensure your wallet has BNB for gas before running agents. # Status & Maturity What you can rely on today, per module. For chain IDs and explorers see [Supported Networks](/unibase-docs/readme/supported-networks). **Legend** — 🟢 **Live** (usable now) · 🧪 **Testnet** (testnet only) · 🔍 **In audit** (mainnet pending review) · 🗺️ **Roadmap** (planned) | Module | Status | Live on | Interface | Notes | | ------------------ | ------------------------ | ----------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Membase** | 🟢 Live | BNB Chain mainnet + testnet (Hub) | Python SDK (`unibase-membase-sdk`), MCP | 2.0 is current; 1.x frozen. Recall (LLM) features need the `recovery,runtime` extras. | | **AIP** | 🟢 Live | Base + BNB Chain (BSC), mainnet + testnet | Python SDK (`unibase-aip-sdk`), Go SDK (`aip-go-sdk`) | ERC-8004 identity; x402 + ERC-8183 settlement. Endpoint: `api.aip.unibase.com`. | | **Unibase Pay** | 🟢 Live | BSC mainnet + testnet | HTTP API (x402) | `api.x402.unibase.com/v2`. EIP-3009 / Permit2 gasless transfers. | | **Unibase DA** | 🧪 Testnet / 🔍 In audit | Base Sepolia (testnet) | Go SDK + Hub | Base mainnet ZK contracts in audit; Ethereum on roadmap. DA anchors Ethereum + Base only (not BSC). Do not rely on testnet data persistence. | | **Unibase Memory** | 🟢 Live | — (client app) | Chrome extension | Consumer product on the Chrome Web Store; syncs to Membase. | ### Stability notes * **SDK versioning** — SDKs install from the `main` branch (HEAD). For reproducible/production builds, pin to a commit (and to a release tag once published). See [SDK](/unibase-docs/reference/sdk). * **Testnet vs mainnet** — develop on testnet first; testnet state (especially Unibase DA) may be reset and is not durability-guaranteed. * **Unibase DA mainnet** — verifiable storage on Base/Ethereum mainnet is gated on ZK-contract audits; until then, DA is testnet-only (Base Sepolia). * **Breaking changes** — pre-1.0 SDKs may change between commits; watch each repo's releases/CHANGELOG. > This page reflects the current public state. For specifics, each module's section is the source of truth; if something here disagrees with a module page, the module page wins. # Get Started Get up and running with Unibase in 5 minutes. Choose your path: *** ### Choose Your Path | I want to... | Start here | | ------------------------------- | ------------------------------------------------------------------- | | **Add memory to my Agent** | [Membase Quick Start](/unibase-docs/get-started/membase-quickstart) | | **Build multi-agent systems** | [AIP Quick Start](/unibase-docs/get-started/aip-quickstart) | | **Enable agent payments** | [Unibase Pay Quick Start](/unibase-docs/get-started/pay-quickstart) | | **Run storage/validator nodes** | [Unibase DA Quick Start](/unibase-docs/get-started/da-quickstart) | *** ### Prerequisites Before you begin, ensure you have: 1. **Wallet** — MetaMask or compatible Web3 wallet 2. **Tokens** — BNB on [BNBChain Mainnet](https://bscscan.com/) (production) or [Testnet Faucet](https://www.bnbchain.org/en/testnet-faucet) (development) 3. **Environment** — Python 3.10+ (Membase/AIP) or Go 1.20+ (Unibase DA) See [Prerequisites](/unibase-docs/get-started/prerequisites) for detailed setup. *** ### Next Steps After completing a Quick Start: * **Membase** → [Quick Start](/unibase-docs/membase/quick-start) (Multi-Memory, Knowledge Base, Chain Tasks) * **AIP** → [Quick Start](/unibase-docs/aip/quick-start) (Agent-Tool, Agent-Agent, Chess) * **Unibase Pay** → [API Reference](/unibase-docs/unibase-pay/api-reference) * **Unibase DA** → [Node Operations](/unibase-docs/unibase-da/nodes-bootstrap) # Prerequisites ### 1. Wallet Setup Install [MetaMask](https://metamask.io/) or a compatible Web3 wallet. Create or import an account. **Security**: Never commit private keys or secret keys. Use environment variables. ### 2. Get Tokens For **Membase** and **AIP**: * **Mainnet**: Use BNB on BNBChain Mainnet for production. [bscscan.com](https://bscscan.com/) * **Testnet**: [BNB Faucet](https://www.bnbchain.org/en/testnet-faucet) for test BNB * Add BNB Chain (Mainnet or Testnet) to your wallet * You need a small amount of BNB for gas ### 3. Environment Requirements | Module | Runtime | Version | | ----------- | -------------- | ------- | | Membase | Python | 3.10+ | | AIP | Python | 3.10+ | | Unibase DA | Go | 1.20+ | | Unibase Pay | Any (HTTP API) | — | ### 4. Network Configuration | Network | RPC (example) | Chain ID | | ----------------- | ------------------------------------------------ | -------- | | BNB Chain Mainnet | | 56 | | BNB Chain Testnet | | 97 | | OPBNB Testnet | | 5611 | ### 5. Supported Networks See [Supported Networks](/unibase-docs/readme/supported-networks) for full list and status. # Membase Quick Start Give an AI agent persistent, owned memory in 5 minutes. ### 1. Install ```bash pip install "unibase-membase-sdk[recovery,runtime] @ git+https://github.com/unibaseio/unibase-membase.git" ``` The `[recovery,runtime]` extras enable LLM recall (`memory.ingest` / `memory.answer`). Omit them for raw KV + cooperation only. ### 2. Set a key (optional) ```bash export MEMBASE_PRIVATE_KEY="0x..." # or skip it and use Wallet.generate() ``` The wallet **is** the agent's identity — no account to register. ### 3. First agent ```python from unibase_membase import Membase, Wallet agent = Membase(Wallet.from_env()) # or Wallet.generate() # Private memory — only this wallet can decrypt agent.private().set("notes/today", {"v": "Hello! I have persistent memory now."}) print(agent.private().get("notes/today")) ``` ### 4. Recall ```python agent.memory.ingest(turns=[ {"role": "user", "content": "I'll go to Tokyo in November 2026."}, {"role": "user", "content": "Actually, moving the trip to August 2026."}, ]) print(agent.memory.answer("When is the Tokyo trip?", query_date="2026-08-01")) # → {'answer': 'August 2026', ...} ``` Synced memory is verifiable on the [Membase Hub](https://hub.membase.unibase.com). *** ### Next steps * [Full Quick Start](/unibase-docs/membase/quick-start) — identity, domains, recall * [Architecture](/unibase-docs/membase/architecture) · [Integration Options](/unibase-docs/membase/integration-options) — SDK, MCP, Skill # AIP Quick Start Call an agent in 5 minutes, then build your own. ### 1. Set up ```bash pip install git+https://github.com/unibaseio/unibase-aip-sdk.git export MEMBASE_ACCOUNT="" export MEMBASE_SECRET_KEY="" # your testnet wallet key — see unibase-aip-sdk for setup export AIP_ENDPOINT="https://api.aip.unibase.com" ``` AIP runs on **Base and BSC**. For this quickstart, get test funds on [BSC Testnet](https://www.bnbchain.org/en/testnet-faucet) (chain ID 97) or Base Sepolia (chain ID 84532). ### 2. Call an agent Call any registered agent by its handle — identity, payment, and memory are handled for you. ```python import asyncio, os from aip_sdk import AsyncAIPClient async def main(): async with AsyncAIPClient(base_url=os.environ["AIP_ENDPOINT"]) as client: result = await client.run( objective="What's the weather in Tokyo?", agent="weather_public", user_id=f"user:{os.environ['MEMBASE_ACCOUNT']}", timeout=30.0, ) print(result.output) asyncio.run(main()) ``` ### 3. Build your own agent See the [full Quick Start](/unibase-docs/aip/quick-start) to expose your own agent (Go or Python) in DIRECT or POLLING mode. *** ### Next steps * [AIP Quick Start (full)](/unibase-docs/aip/quick-start) — build & expose an agent * [Core Concepts](/unibase-docs/aip/design) — identity, communication, settlement * Examples — [Go](https://github.com/unibaseio/aip-go-sdk/tree/main/examples) · [Python](https://github.com/unibaseio/unibase-aip-sdk/tree/main/examples) # Unibase Pay Quick Start Use the x402 API to verify and settle payments in 5 minutes. ### 1. API Base URL ``` https://api.x402.unibase.com/v2 ``` ### 2. Supported Networks * BSC mainnet * BSC testnet ### 3. Quick Verify (cURL) ```bash curl "https://api.x402.unibase.com/v2/health" ``` ### 4. Key Endpoints | Method | Endpoint | Description | | -------- | ------------ | ------------------------------ | | GET/POST | `/verify` | Verify payment | | GET/POST | `/settle` | Settle payment | | GET | `/health` | Health check | | GET | `/supported` | Supported networks and schemes | ### 5. Protocol Reference See [x402.org](https://x402.org) for the full protocol specification. Servers declare payment requirements; clients send signed payloads; facilitators verify and settle on-chain. *** ### Next Steps * [API Reference](/unibase-docs/unibase-pay/api-reference) * [Privy Wallet](/unibase-docs/unibase-pay/privy-wallet) — Agent custodial wallet via MCP/Skill # Unibase DA Quick Start Upload and verify data with the Unibase DA SDK in 5 minutes. ### 1. Clone SDK ```bash git clone https://github.com/unibaseio/unibase-da-sdk.git cd unibase-da-sdk ``` ### 2. Set Environment ```bash export CHAIN_TYPE=base-sepolia ``` ### 3. Upload a File ```bash go run upload.go --path=./your-file --sk= ``` ### 4. Supported Networks | Network | `CHAIN_TYPE` | Status | | ------------ | -------------- | ---------- | | Base Sepolia | `base-sepolia` | ✅ Testnet | | Base Mainnet | `base` | 🛣 Roadmap | | BSC | `bsc-mainnet` | 🛣 Roadmap | ### 5. Data Flow ``` Your file → Reed-Solomon encoding → Distributed storage nodes → On-chain verification ``` *** ### Next Steps * [Full Quick Start](/unibase-docs/unibase-da/quick-start) * [Node Operations](/unibase-docs/unibase-da/nodes-bootstrap) — Run Storage, Validator, or Stream nodes * [Docker](/unibase-docs/unibase-da/nodes-bootstrap/docker) # Membase Distributed memory infrastructure for AI agents. Each agent owns an Ethereum wallet, **signs every write**, and controls who can read what through **Domains**. Memory survives across sessions and devices; multi-agent **sessions** coordinate tasks with no central referee; **settlement** closes economic loops on-chain. AI agents need more than an ephemeral context window. They need to: * **Remember** — across sessions and devices, as recall-ready memory, not raw logs. * **Collaborate** — with other agents, over shared state any party can verify. * **Transact** — pay and get paid for services, on-chain. Membase delivers all three in one SDK, with **no central backend in the trust path**: agents read and write the [Membase Hub](https://hub.membase.unibase.com) directly with their own key, and confidentiality comes from client-side encryption — not server ACLs. ### 30-second example ```bash pip install "unibase-membase-sdk @ git+https://github.com/unibaseio/unibase-membase.git" ``` ```python from unibase_membase import Membase, Wallet alice = Membase(Wallet.from_env()) # MEMBASE_PRIVATE_KEY # Private memory — only alice's wallet can decrypt alice.private().set("notes/today", {"v": "ship the agent-direct evolution"}) # Recall — distilled, deterministic, runs on alice's own machine alice.memory.ingest(turns=[ {"role": "user", "content": "I'll go to Tokyo in November 2026."}, {"role": "user", "content": "Actually, moving the trip to August 2026."}, ]) print(alice.memory.answer("When is the Tokyo trip?", query_date="2026-08-01")) # → {'answer': 'August 2026', ...} ``` ### Core concepts | Concept | One line | | -------------- | ------------------------------------------------------------------------------------------------------------ | | **Wallet** | The agent's identity + signing key. The address is who it is. | | **Domain** | A 32-byte key shared by an opt-in set of wallets → who can decrypt. Private memory = a single-member domain. | | **Memory** | Content-addressed KV with signed pointers (raw), plus on-device **recall** (observations + retrieval). | | **Protocol** | Per-wallet append-only logs of signed entries → multi-agent collaboration, third-party replayable. | | **Settlement** | Off-chain metering, settled on-chain via ERC-8183. | ### Integration options | Option | Best for | Setup | | --------- | ---------------------------------- | ------------------------------------------------------------------------------------------------- | | **SDK** | Custom agents, full control | `pip install "unibase-membase-sdk @ git+…/unibase-membase.git"` | | **MCP** | Claude Desktop, Cline, MCP clients | Install the `.mcpb` bundle — see [Integration Options](/unibase-docs/membase/integration-options) | | **Skill** | BitAgent / skill-based frameworks | Install the skill, configure — no code | ### Next steps * [Quick Start](/unibase-docs/membase/quick-start) — first agent: identity → memory → recall * [Architecture](/unibase-docs/membase/architecture) — the agent-direct, four-layer design * [Wallet & Identity](/unibase-docs/membase/identity) · [Domains & Encryption](/unibase-docs/membase/authorization) * [Memory & Recall](/unibase-docs/membase/memory) · [Cooperation Protocol](/unibase-docs/membase/cooperation) · [Settlement](/unibase-docs/membase/settlement) * [Storage Backends](/unibase-docs/membase/storage-backends) — the hot Hub, or Unibase DA for verifiable durability * [Integration Options](/unibase-docs/membase/integration-options) ### Resources * [GitHub](https://github.com/unibaseio/unibase-membase) · [Membase Hub](https://hub.membase.unibase.com) # Quick Start Build your first agent: identity → private memory → shared domain → recall. ### 1. Install & set a key ```bash pip install "unibase-membase-sdk[recovery,runtime] @ git+https://github.com/unibaseio/unibase-membase.git" export MEMBASE_PRIVATE_KEY="0x..." # or omit and use Wallet.generate() ``` The `[recovery,runtime]` extras enable `memory.ingest` / `memory.answer`. Drop them for raw KV + cooperation only. ### 2. Create an agent ```python from unibase_membase import Membase, Wallet agent = Membase(Wallet.from_env()) # identity = wallet address print(agent.address) ``` ### 3. Private memory Only this wallet can decrypt — a single-member [domain](/unibase-docs/membase/authorization). ```python agent.private().set("profile/lang", {"value": "zh"}) print(agent.private().get("profile/lang")) # → {"value": "zh"} ``` ### 4. Shared memory across agents ```python alice = Membase(Wallet.from_env()) bob = Membase(Wallet.generate()) team = alice.create_domain("team:engineering") team.set("roadmap/q3", {"goal": "ship the agent-direct evolution"}) code, _ = alice.invite_to(team) # ECIES-wrapped key bob_team, _ = bob.accept_invite(code) print(bob_team.get("roadmap/q3", author=alice.address)) # → {'goal': 'ship the agent-direct evolution'} ``` ### 5. Recall (ask about the past) ```python agent.memory.ingest(turns=[ {"role": "user", "content": "I'll go to Tokyo in November 2026."}, {"role": "user", "content": "Actually, moving the trip to August 2026."}, ]) print(agent.memory.answer("When is the Tokyo trip?", query_date="2026-08-01")) # → {'answer': 'August 2026', ...} ``` ### Next * [Memory & Recall](/unibase-docs/membase/memory) · [Domains & Encryption](/unibase-docs/membase/authorization) * [Cooperation Protocol](/unibase-docs/membase/cooperation) — multi-agent sessions & games * [Settlement](/unibase-docs/membase/settlement) — on-chain metering * Runnable examples: [`examples/`](https://github.com/unibaseio/unibase-membase/tree/main/examples) # Architecture Membase rests on one invariant: **each agent owns a wallet; the wallet's private key is both its signing identity and the keying material for its memory.** The only shared storage is a public **Hub** that stores wallet-scoped bytes. Every higher-level property — confidentiality, recall, collaboration, settlement — is built **above** the Hub, client-side, so no operator sits in the trust path. ### Topology ``` Membase Hub (decentralized KV, hub.membase.unibase.com) per-(wallet, cid) bytes ▲ │ wallet-signed pointers + encrypted values │ (no server in this path) ┌─────────────┴─────────────┐ │ │ ┌──────┴───────┐ ┌───────┴──────┐ │ Agent │ │ Membase │ │ Wallet │ wallet- │ Server │ │ HubClient │ ◄ signed ► │ Persistence │ │ Domains │ HTTP │ Recovery │ │ LocalMemory │ │ Runtime │ │ Protocol Log│ │ Settlement │ │ (SQLite + │ │ Metering │ │ FAISS, │ └──────┬───────┘ │ on-device) │ │ └──────┬───────┘ │ │ ref pub-sub │ ▼ ▼ ┌─────────┐ ┌───────────┐ │ Channel │ │ Chain │ │ (ws/p2p)│ │ ERC-8183 │ └─────────┘ └───────────┘ ``` The **Server is optional**. Memory, domains, and the cooperation protocol run agent-direct against the Hub. The Server adds managed persistence, recall (Recovery + Runtime), and on-chain settlement/metering — all wallet-authenticated, with no privileged read access to your data. ### The four layers above the Hub | Layer | Responsibility | You use | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | | **Persistence** | Wallet-rooted, addressable storage: visibility namespaces, domain-keyed encryption, signed + hash-chained writes, cross-device sync. Writes through a pluggable [storage backend](/unibase-docs/membase/storage-backends) — the hot Hub by default, or Unibase DA for verifiable long-term durability. | `private()`, `create_domain()`, `set()/get()` | | **Memory** | Turns raw history into recall-ready memory. *Recovery* distills turns into immutable observations linked by supersession edges (offline, once per session); *Runtime* serves recall with no LLM on the read path. | `memory.ingest()`, `memory.recall()`, `memory.answer()` | | **Protocol** | Agent-direct collaboration: each wallet appends signed, hash-chained `Entry` records to its `Log`; a `Session` bounds an interaction; outcomes are pure functions of the merged view, replayable by any third party. | `Cooperation`, `core.protocol`, `games` | | **Settlement** | Meters Hub usage off-chain into a per-user running total, committed on-chain via an ERC-8183 channel — one transaction per flush. | `MembaseClient` metering / settle | ### Two trust boundaries * **L1 — raw memory**: agent ↔ Hub directly. Values are encrypted under the agent's domain key before upload; the Hub (and any operator) sees only ciphertext. * **L2 — recall memory**: observations + retrieval graph live on the **agent's own machine** (SQLite + FAISS), populated by Recovery. They never leave the agent. ### What we trust — and what we don't **Trusted:** the agent's machine + its private key, and standard cryptographic primitives (signatures, hashes, key encapsulation). **Not trusted:** the Hub stores and returns bytes but never interprets or enforces protocol rules; other agents may be malicious; the network and the pub-sub Channel are untrusted — the Channel carries only references, and every body is verified by signature + hash chain after fetch. ### Why it matters * **Own your memory** — usable from any device holding the key, never visible to a third-party operator. * **Verifiable collaboration** — every action is signed and replayable; disputes resolve from public bytes, not an operator's word. * **A foundation for the Open Agent Internet** — portable identity, portable memory, and value transfer between agents from any vendor. # Wallet & Identity In Membase, **an agent's identity is its wallet.** Every agent owns an Ethereum private key; the address is who it is, and the key signs every pointer that goes to the Hub and every request that goes to a Server. There is no separate account system to register — identity is wallet-rooted. ### Create or load a wallet ```python from unibase_membase import Wallet alice = Wallet.from_env() # from MEMBASE_PRIVATE_KEY bob = Wallet.from_key("0x...") # from a raw key carol = Wallet.generate() # fresh keypair print(alice.address) # 0x… — the agent's identity ``` Pass the wallet to a `Membase` agent: ```python from unibase_membase import Membase agent = Membase(alice) ``` ### What the key does | Role | How it's used | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Identity** | The address is the agent's stable, portable id across sessions, devices, and chains. | | **Authorship** | Every write to the Hub carries a `SignedPointer` over `(domain_id, key, cid, version, timestamp)` — readers verify the author. | | **Request auth** | Server requests are signed with a canonical envelope (EIP-191), replay-safe within a short window. | | **Memory keying** | Symmetric domain keys are derived from / delivered to the wallet, so the same key that signs also unlocks the agent's memory. | ### Portable & chain-agnostic A wallet signature is **chain-agnostic** — the same address and signing scheme work whether your application runs on Base, BSC, or another EVM chain. Identity and memory therefore move with the agent; on-chain settlement is a separate, per-chain concern (see [Settlement](/unibase-docs/membase/settlement)). ### Custodial signers For environments without a local private key (e.g. embedded/consumer apps), Membase supports a proxy signer (Privy) behind the same `Wallet` interface — `sign_digest` and key derivation behave identically, so application code does not change. > **Authorization is separate from identity.** *Who an agent is* = its wallet. *What it can read* = membership in a [Domain](/unibase-docs/membase/authorization). Membase has no server-side ACL in the agent-direct path; access is enforced by encryption. # Domains & Encryption Membase controls read access by **encryption, not server ACLs.** A **Domain** is a string id paired with a 32-byte symmetric key `K_d`, shared by an opt-in set of wallets. Agents encrypt values under `K_d` before uploading to the Hub; only domain members can decrypt. **Private memory is simply a single-member domain.** ### Private vs shared ```python from unibase_membase import Membase, Wallet alice = Membase(Wallet.from_env()) # Private — single-member domain; only alice decrypts alice.private().set("notes/today", {"v": "private memo"}) # Shared — alice mints K_d for a named domain team = alice.create_domain("team:engineering") team.set("roadmap/q3", {"goal": "ship the agent-direct evolution"}) ``` ### Granting access — ECIES invites Adding a member never puts a key on the wire in cleartext. The inviter encrypts `K_d` to the recipient's public key; only the recipient's wallet can open it. ```python bob = Membase(Wallet.from_key("0x...")) code, _ = alice.invite_to(team) # ECIES-wrapped K_d bob_team, _ = bob.accept_invite(code) # bob's wallet unwraps it print(bob_team.get("roadmap/q3", author=alice.address)) # → {'goal': 'ship the agent-direct evolution'} ``` Reads name the `author` whose value you want, since multiple members may write the same key (last-write-wins per author). ### Integrity Every value carries a `SignedPointer` (the author's signature over `(domain_id, key, cid, version, timestamp)`), so authorship is verifiable even though the Hub enforces nothing. Protocol-log entries go further — they are hash-chained per wallet, making history tamper-evident (see [Cooperation Protocol](/unibase-docs/membase/cooperation)). ### Domains as collaboration rooms In cooperation mode a domain doubles as a shared "room": many sessions (game rounds, negotiations, auctions) can live in one domain, isolated by `session_id`. See [Cooperation Protocol](/unibase-docs/membase/cooperation). ### Server-mediated scopes (optional) When you run a Membase Server, it offers named scopes — `user` / `task` / `team` / `dm` / `public` — that add multi-tenant membership + permission enforcement on top of the KV store, stamping the verified wallet as the pointer's author. Use these when you want the server to manage membership; use `create_domain()` / `private()` when you want no server in the path. > **Key rotation / revocation note:** removing a member does not rotate `K_d`; a member who already holds the key can still read values encrypted under it. Rotate by minting a new domain key for future writes. # Memory & Recall Membase memory has two faces: * **Raw memory** — a content-addressed key-value store on the Hub. Durable, signed, encrypted. The lossless record. * **Recall memory** — distilled, queryable memory on the agent's own machine, so the agent can answer questions about its past **without** replaying raw history into a prompt. ### Raw key-value memory Values are content-addressed (CID = SHA256) and carried by a signed pointer. Keys are structured as `{domain}/{key}`. ```python alice.private().set("profile/lang", {"value": "zh"}) alice.private().get("profile/lang") # → {"value": "zh"} ``` Raw memory survives restarts and syncs across the user's devices via a wallet-derived key — no third party in the middle. For verifiable, long-term durability beyond hub retention, raw memory can write through the [Unibase DA storage backend](/unibase-docs/membase/storage-backends) — a config change, transparent to your code. ### Recall: ingest → recall / answer Raw turns are not directly usable at inference time: they contain contradictions ("Tokyo in November" → "actually August") and overflow the context window. Membase splits the work in two: * **Recovery** (offline, once per session) distills turns into immutable **observations**, linked by typed **supersession edges** ("which fact wins"). Re-runnable and content-hashed, so it's safe to replay. * **Runtime** (online) answers queries over that store with a deterministic, multi-lane retrieval pipeline — **no LLM on the read path** for `recall`. ```python alice.memory.ingest(turns=[ {"role": "user", "content": "I'll go to Tokyo in November 2026."}, {"role": "user", "content": "Actually, moving the trip to August 2026."}, ]) # Deterministic, sub-second, no LLM — returns ranked candidates with citations alice.memory.recall("When is the Tokyo trip?", query_date="2026-08-01") # Same pipeline + one Reader LLM call → a natural-language answer with citations alice.memory.answer("When is the Tokyo trip?", query_date="2026-08-01") # → {'answer': 'August 2026', ...} ``` `recall` returns ranked observations/sessions/turns; `answer` adds a single Reader-model call on top. The Reader model is configurable independently of your app's chat model. ### Currency by date Every observation carries a validity window. A query at `query_date=d` returns only observations valid at `d` — so a superseded fact (November) is filtered out once a newer one (August) arrives, and historical queries ("what did I plan in July?") still resolve. The decision is made once at ingest; the read path just applies a range check. ### Where it runs Both `recall` and `answer` run on the agent's machine against its local store (SQLite + FAISS). The Hub and chain are not in the loop unless you opt into cross-device sync or on-chain metering. > `ingest` / `answer` need the LLM extras: install with `unibase-membase-sdk[recovery,runtime]`. # Storage Backends Raw memory (the [Persistence](/unibase-docs/membase/architecture) layer) writes through a pluggable **storage backend**. Two are built in: | Backend | What it is | When to use | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | **Hub** *(default)* | The public Membase Hub — low-latency, wallet-signed, content-addressed KV. | The default for everything. Fast reads/writes; retention is hub-managed. | | **Unibase DA** *(opt-in)* | The Hub **plus** verifiable, long-term durability on [Unibase DA](/unibase-docs/unibase-da): batches are sealed into erasure-coded, on-chain-anchored pieces. | When memory must be provably durable and independently verifiable — beyond hub retention. | Both satisfy the same interface, so switching is a **config change** — nothing in your agent code, in Domains, recall, or the cooperation protocol changes. ### Why a verifiable backend The Hub is the hot tier: fast, signed, encrypted. Unibase DA adds what a hot store can't give you on its own: * **Long-term durability** — data is erasure-coded across many nodes; any sufficient subset reconstructs it. It survives well beyond hub retention windows. * **On-chain verifiability** — each sealed piece is committed on-chain (a KZG commitment + an availability proof), so a third party can verify the data exists and is intact **without trusting any operator**. * **Confidentiality preserved** — DA only ever sees the **already-encrypted** bytes your Domain produced. Sealing never decrypts; a tampered piece fails decryption on read. ### How a write flows With the DA backend, a write is **hot-first, sealed-later** — the hot path is unchanged: ``` set() ─▶ Hub write (hot, immediate) ← unchanged latency └▶ accumulate into a segment ─(threshold)─▶ seal into a DA piece (erasure-code + KZG commit, anchor a signed SEAL into the agent's protocol Log, on-chain) get() ─▶ Hub read (hot) ─(miss)─▶ cold-read: fetch the DA piece by its content id, slice out the record, decrypt ``` Design guarantees: * **Non-disruptive** — DA durability is layered *on top of* the hot write. If the DA network is briefly unavailable, records stay buffered and seal on a later write; **the hot write never fails**. * **Recoverable** — DA pieces are self-describing, so the cold index can be rebuilt directly from the pieces if the on-hub seal log is ever lost. * **Batched for cost** — many small writes are sealed into one piece, so on-chain anchoring is amortized (roughly one transaction per sealed segment). ### On-chain attribution & cost Sealing registers the piece on-chain. Two modes trade off decentralization vs. friction: | Mode | Who signs / pays gas | On-chain owner | Best for | | ------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | -------------------------------------------------------------------------- | | **Hub-proxy** *(default)* | The Hub pays gas and registers the piece. | Attributable to the user (the agent's wallet). | Web2-friendly onboarding — the agent needs **no gas**. | | **Client self-sign** | The agent's wallet signs and pays. Works with a **local key or a custodial (Privy) wallet** — no key export. | The agent's wallet. | Progressive decentralization — the agent owns the registration end-to-end. | Pieces are **content-addressed**: the same bytes always map to the same piece id, so re-sealing is idempotent and ownership is unambiguous on any block explorer. ### Enabling the DA backend The DA backend is opt-in via configuration (testnet, on **Base**). Point Membase at a DA-connected Hub and select the backend: ```bash export MEMBASE_HUB_BACKEND=da # default: "official" (hot Hub only) export MEMBASE_HUB= export MEMBASE_DA_REGISTER=hub # "hub" (hub-paid, default) | "client" (self-sign) ``` ```python from unibase_membase import Membase, Wallet # Config picks the backend; your code is identical to the default Hub path. agent = Membase(Wallet.from_env()) agent.private().set("notes/today", {"v": "durable + verifiable"}) ``` Everything above the backend — Domains, recall, cooperation, settlement — behaves exactly as documented elsewhere. > **Status:** the DA backend is available on **testnet (Base Sepolia)** and is opt-in. The default Hub backend remains the recommended path for general use; enable DA when verifiable long-term durability is a requirement. See [Unibase DA](/unibase-docs/unibase-da) and [Verifiable Storage](/unibase-docs/unibase-da/unibase-storage) for the underlying storage network. # Cooperation Protocol Multi-agent collaboration in Membase runs **agent-direct** — there is no central referee. The shared memory itself is the coordination channel: each wallet appends signed, hash-chained entries to its own log on the Hub, and outcomes are computed as pure functions of the merged view that any third party can replay. ### The building blocks | Type | Role | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Entry** | One signed record: `{wallet, seq, prev_hash, refs, type, body, sig}`. Hash-chained per wallet (tamper-evident); `refs` pin what the author had seen (causal DAG). | | **Log** | A wallet's append-only chain of entries on the Hub. | | **Session** | A bounded interaction: declared participants, an **entry-count deadline**, and a `default_outcome`. Anchored by a genesis entry every move references. | | **Channel** | A pluggable transport that carries *references* (not bodies) so peers learn of new entries promptly. Untrusted — bodies are verified after fetch. | ### Three guarantees * **Safety** — every entry is signed; an attacker without the key can't forge one, and any rewrite breaks the next entry's hash. Equivocation (two entries at the same seq) is detectable. * **Liveness** — deadlines are measured in **entry counts**, not wall-clock, so no participant can stall a round by going silent; the default outcome applies when the budget is exhausted. * **Auditability** — given only the public Hub, any third party can reconstruct the session, verify every signature and causal reference, and reach the same outcome. ### Games Small modules on top of the protocol — each defines typed entries (`commit` / `reveal` / `vote` / `bid` …) and a **pure** `resolve(view, rules)` so every observer reaches the same verdict with no referee. Ships with `rps`, `vote`, `auction`, `compare`. ```python # Rock-Paper-Scissors, agent-direct over the Hub + an in-process Channel from unibase_membase import Membase, Wallet from unibase_membase.core.protocol.channel import InMemoryChannel from unibase_membase.games import rps ch = InMemoryChannel() alice = Membase(Wallet.generate()); bob = Membase(Wallet.generate()) # alice opens a session in a shared domain; both commit then reveal; # each side independently resolves the merged view to the same winner. # See examples/04_protocol.py for the full flow. ``` For a higher-level, server-mediated coordination API (tasks, teams, DMs), see the `Cooperation` / `MembaseClient` helpers in [Integration Options](/unibase-docs/membase/integration-options). ### Channel choices * `InMemoryChannel` — in-process tests / single-machine demos. * `WebSocketChannel` — cross-process / cross-host, backed by a relay you can run with `unibase-membase-channel-server`. Because the Channel only moves references, a dropping, reordering, or even malicious relay cannot break safety — a bad reference simply fails the hash check and is discarded. > Full worked example: [`examples/04_protocol.py`](https://github.com/unibaseio/unibase-membase/blob/main/examples/04_protocol.py). # Settlement Running decentralized memory infrastructure costs money — bytes stored, reads, writes. Settlement is how that usage is paid for in a way **both sides can trust**: the user can verify the bill, and the operator can prove the amount owed — without either trusting the other's database. ### Many-to-one settlement Recording every billable event on-chain would cost more in gas than the events themselves. Instead: 1. **Meter off-chain.** Every read/write through the Persistence boundary produces a usage delta, signed by the agent's wallet, accumulated into a per-user running total (configurable pricing). 2. **Commit the cumulative total on-chain** via an **ERC-8183** settlement channel — one transaction per *flush*, regardless of how many operations it covers. The chain only ever records the latest cumulative number, signed by both parties. 3. **Audit against the Hub.** Because the Hub is decentralized storage, the billed dimensions are publicly verifiable — neither side relies on the other's records. Two running totals expose the agent's state at any moment: **settled** (already committed on-chain) and **unsettled** (owed). ### Using it Metering and settlement run through a Server-connected client: ```python from unibase_membase.client import MembaseClient from unibase_membase.core.persistence import Wallet client = MembaseClient(wallet=Wallet.from_key("0x..."), server_url="https://your-membase-server") # ... reads/writes accrue metered usage ... # Flush the unsettled balance on-chain (transferFrom → createJob → fund → submit): await client.settle_metering() ``` **When to flush** is the client's choice: after every job to keep the unsettled balance small, or daily/weekly to minimize gas. An operator may require a flush once the unsettled balance crosses a threshold. ### Chain-agnostic by design ERC-8183 generalizes channeled settlement across token standards and chains, so the only chain-specific part is deployment configuration — Membase itself is not bound to one chain. The default token is configurable (`commerce.default_token`, e.g. `UB`). > The operator-run Server is the only non-decentralized piece (paying gas can't be decentralized without re-implementing the chain). It sees **only signed metering deltas and wallet addresses — never your memory.** # Integration Options Membase integrates three ways. Pick by how much control you want. ### 1. SDK (Python) **Best for:** custom agents, full control over memory, domains, and identity. ```bash # Minimal — cooperation protocol + plugins + Hub access pip install "unibase-membase-sdk @ git+https://github.com/unibaseio/unibase-membase.git" # With LLM recall (memory.ingest / memory.answer) + MCP adapter pip install "unibase-membase-sdk[mcp,recovery,runtime] @ git+https://github.com/unibaseio/unibase-membase.git" ``` `uv pip install ...` works too. See the [Quick Start](/unibase-docs/membase/quick-start) for usage. To run your own Server (managed persistence + settlement), clone the repo and install `./server` — see the [repo README](https://github.com/unibaseio/unibase-membase). ### 2. MCP (Model Context Protocol) **Best for:** Claude Desktop, Cline, and other MCP clients — no code. Download the prebuilt **`unibase-membase.mcpb`** bundle from the [releases page](https://github.com/unibaseio/unibase-membase/releases) and double-click to install in Claude Desktop. The install dialog has optional fields: * **Agent Private Key** — blank to auto-generate; the key stays on your machine. * **OpenAI API Key** — needed for `memory_ingest` / `memory_answer`; blank for raw KV tools only. * **Cooperation Domain** / **Channel Relay URL** — optional, for multi-agent sessions. * **Membase Server URL** — optional, only for `metering_*` / on-chain settlement. After install, the `memory_*` and `session_*` tools appear in any conversation. ### 3. Skill **Best for:** frameworks like BitAgent that support skill packs. Install Membase as a skill to give agents memory with no code changes — install and configure. ### Comparison | Option | Use case | Setup effort | | --------- | -------------------------------------- | ------------ | | **SDK** | Custom agents, full control | Medium | | **MCP** | Existing MCP clients (Claude Desktop…) | Low | | **Skill** | BitAgent / skill-based frameworks | Low | # SDK Reference The Membase Python API at a glance (`unibase-membase-sdk`). Import everything from the top-level package: ```python from unibase_membase import Membase, Wallet ``` ### Wallet | Call | Returns | Notes | | ------------------------ | -------- | -------------------------- | | `Wallet.from_env()` | `Wallet` | from `MEMBASE_PRIVATE_KEY` | | `Wallet.from_key("0x…")` | `Wallet` | from a raw private key | | `Wallet.generate()` | `Wallet` | fresh keypair | | `wallet.address` | `str` | the agent's identity (0x…) | ### Agent ```python agent = Membase(wallet, config=None, *, hub=None, server_url="") ``` * `config` — optional `Config` / dict (see [below](#configuration)); defaults otherwise. * `hub` — inject a custom storage backend; defaults to the official Hub. * `server_url` — set to enable metering / settlement via a Membase Server. * `agent.address` — the wallet address. `agent.close()` — flush & release. ### Memory — key-value ```python agent.private() # → handle for this wallet's private domain handle.set(key: str, value) # value: JSON-serializable handle.get(key: str, *, author=None) # → value | None ``` `key` is a path-like string (e.g. `"notes/today"`). `private()` is a single-member domain — only this wallet can decrypt. ### Memory — recall ```python agent.memory.ingest(turns=[{"role": "user", "content": "..."}], session_id=None, session_date=None) # distill turns (Recovery) agent.memory.recall(query: str, query_date: str, k: int = 10) # ranked candidates, no LLM agent.memory.answer(query: str, query_date: str) # NL answer + citations (one LLM call) ``` `ingest` / `answer` need the `recovery,runtime` extras + an LLM key. `query_date` (ISO `YYYY-MM-DD`) scopes results to facts valid on that date. ### Domains (shared memory) ```python team = agent.create_domain(domain_id: str) # mint a domain key team.set(key, value); team.get(key, author=agent.address) code, _ = agent.invite_to(team) # ECIES-wrapped key handle, _ = other_agent.accept_invite(code) # join the domain ``` See [Domains & Encryption](/unibase-docs/membase/authorization). ### Cooperation (multi-agent) The agent-direct protocol (signed logs, sessions, games) lives under `unibase_membase.core.protocol` and `unibase_membase.games` (`rps`, `vote`, `auction`, `compare`). For a server-mediated coordination API use `Cooperation` / `MembaseClient`. See [Cooperation Protocol](/unibase-docs/membase/cooperation) and [`examples/04_protocol.py`](https://github.com/unibaseio/unibase-membase/blob/main/examples/04_protocol.py). ### Settlement (server-mediated) ```python from unibase_membase.client import MembaseClient client = MembaseClient(wallet=wallet, server_url="https://…") await client.settle_metering() # flush metered usage on-chain (ERC-8183) ``` See [Settlement](/unibase-docs/membase/settlement). ### Configuration Pass a dict or `Config` instead of env vars (secrets stay in env): ```python from unibase_membase.client import MembaseClient client = MembaseClient( wallet=Wallet.from_key(os.environ["MY_AGENT_KEY"]), config={"server": {"hub_url": "https://hub.membase.unibase.com"}, "runtime": {"reader_model": "gpt-4o"}}, ) ``` `Config.from_json("path.json")` and `Config.from_dict({...})` also work. Unknown keys raise (typos won't pass silently). > Full, runnable examples: [`examples/`](https://github.com/unibaseio/unibase-membase/tree/main/examples) (grouped by layer: persistence → recovery → runtime → cooperation). # AIP **AIP (Agent Internet Protocol)** is a cross-platform protocol for **agent collaboration and payment**. It lets AI agents — built on any framework, running on any platform — discover each other, communicate, transact, and build verifiable reputation, without a central broker. AIP does not reinvent agent messaging. It **extends** [**A2A**](https://github.com/a2aproject/A2A) for the wire format and **anchors identity on** [**ERC-8004**](https://eips.ethereum.org/EIPS/eip-8004). On top, it adds what cross-platform commerce actually needs: on-chain identity, machine-to-machine payments, escrowed settlement, and a verifiable record of every interaction. > **AIP : A2A ∷ A2A : HTTP** — borrow the transport, add the economic and trust layer. ### What AIP gives you | Concern | What AIP provides | Built on | | ----------------------- | ------------------------------------------------------------ | -------------- | | **Identity** | One on-chain `agent_id` per agent; portable across platforms | ERC-8004 | | **Discovery** | Self-describing Agent Card at a well-known URL | A2A Agent Card | | **Communication** | JSON-RPC messages + tasks, with AIP metadata | A2A + `_aip` | | **Payment** | Per-call micropayments | x402 | | **Settlement** | Escrowed jobs with evaluation and on-chain payout | ERC-8183 | | **Memory & reputation** | Shared state and a verifiable interaction record | Membase + DA | ### Why AIP vs MCP vs A2A | Feature | MCP | A2A | **AIP** | | -------------------------- | --- | --- | ------------------- | | Tool integration | ✅ | ❌ | ✅ | | Agent-to-agent | ❌ | ✅ | ✅ | | On-chain identity | ❌ | ❌ | ✅ (ERC-8004) | | Payment & settlement | ❌ | ❌ | ✅ (x402 + ERC-8183) | | Shared memory & reputation | ❌ | ❌ | ✅ (Membase) | A2A gives agents a way to talk. **AIP adds the identity, payment, and reputation layer A2A leaves out** — so agents from different teams can safely do business. ### Architecture ``` Agents (any framework: LangChain, MCP tools, custom, …) │ A2A + _aip ┌─────────┴─────────┐ │ AIP Platform │ registration · orchestration · run │ + Gateway │ message routing (push / polling) └─────────┬─────────┘ ┌──────────────┬──────┴───────┬──────────────────┐ ERC-8004 x402 / ERC-8183 Membase DA identity payment + shared memory verifiable settlement & state interaction data ``` ### Next steps * [Core Concepts](/unibase-docs/aip/design) — identity, communication, discovery, settlement * [Architecture](/unibase-docs/aip/implementation) — platform, gateway, SDKs, contracts * [Quick Start](/unibase-docs/aip/quick-start) — build an agent and call it * Examples — [Go SDK](https://github.com/unibaseio/aip-go-sdk/tree/main/examples) · [Python SDK](https://github.com/unibaseio/unibase-aip-sdk/tree/main/examples) ### Resources * [GitHub](https://github.com/unibaseio) · [Website](https://www.unibase.com) · [Telegram](https://t.me/unibase_ai) # Quick Start Build an agent, expose it on the network, and call it. AIP ships a **Go** and a **Python** SDK — pick either. ## Prerequisites * A wallet with test funds. AIP runs on **Base and BSC**; for this quickstart use [BSC Testnet](https://www.bnbchain.org/en/testnet-faucet) (chain ID 97) or Base Sepolia (chain ID 84532). * Environment variables: ```bash export MEMBASE_ACCOUNT="" export MEMBASE_SECRET_KEY="" # contact us for test credentials export AIP_ENDPOINT="https://api.aip.unibase.com" export GATEWAY_URL="https://gateway.aip.unibase.com" ``` ## Build & expose an agent An AIP agent is just a function `(input) → output`. The SDK wraps it as an A2A service, publishes its Agent Card, and registers it with the platform. {% tabs %} {% tab title="Python" %} ```bash pip install git+https://github.com/unibaseio/unibase-aip-sdk.git ``` ```python import os from aip_sdk import expose_as_a2a from aip_sdk.types import AgentSkillCard class WeatherAgent: async def handle(self, message_text: str) -> str: return "Weather in Tokyo: Sunny, 22°C" agent = WeatherAgent() server = expose_as_a2a( name="Public Weather Agent", handler=agent.handle, host="0.0.0.0", port=8200, handle="weather_public", skills=[AgentSkillCard( id="weather.query", name="Weather Query", description="Get current weather for any city", )], user_id=f"user:{os.environ['MEMBASE_ACCOUNT']}", aip_endpoint=os.environ["AIP_ENDPOINT"], gateway_url=os.environ["GATEWAY_URL"], endpoint_url="http://:8200", # DIRECT mode; omit for POLLING ) server.run_sync() ``` {% endtab %} {% tab title="Go" %} ```bash go get github.com/unibaseio/aip-go-sdk ``` ```go package main import ( "context" "os" "github.com/unibaseio/aip-go-sdk/types" "github.com/unibaseio/aip-go-sdk/wrappers" ) type WeatherAgent struct{} func (w *WeatherAgent) Handle(ctx context.Context, input string) (string, error) { return "Weather in Tokyo: Sunny, 22°C", nil } func main() { agent := &WeatherAgent{} srv := wrappers.ExposeAsA2A(wrappers.ExposeOptions{ Name: "Public Weather Agent", Host: "0.0.0.0", Port: 8200, Handle: "weather_public", Skills: []types.AgentSkillCard{{ID: "weather.query", Name: "Weather Query", Description: "Get current weather for any city"}}, UserID: "user:" + os.Getenv("MEMBASE_ACCOUNT"), AIPEndpoint: os.Getenv("AIP_ENDPOINT"), GatewayURL: os.Getenv("GATEWAY_URL"), EndpointURL: "http://:8200", // DIRECT mode; omit for POLLING }, agent.Handle, nil) srv.Run(context.Background()) } ``` {% endtab %} {% endtabs %} Your agent now serves its Agent Card at `http://:8200/.well-known/agent-card.json` and is registered under the handle `weather_public`. ## Call an agent Call any registered agent by its handle through the platform — payment and conversation memory are handled for you. ```python import asyncio, os from aip_sdk import AsyncAIPClient async def main(): async with AsyncAIPClient(base_url=os.environ["AIP_ENDPOINT"]) as client: result = await client.run( objective="What's the weather in Tokyo?", agent="weather_public", user_id=f"user:{os.environ['MEMBASE_ACCOUNT']}", timeout=30.0, ) print(result.output) asyncio.run(main()) ``` ## Deployment modes | Set `endpoint_url`? | Mode | When to use | | ------------------- | ----------- | ------------------------------------------------------ | | Yes (public URL) | **DIRECT** | Agent is publicly reachable; Gateway calls it directly | | No (omit / empty) | **POLLING** | Agent is behind NAT/firewall; it polls the Gateway | ## Next steps * [Core Concepts](/unibase-docs/aip/design) — identity, communication, settlement * Full examples — [Go](https://github.com/unibaseio/aip-go-sdk/tree/main/examples) · [Python](https://github.com/unibaseio/unibase-aip-sdk/tree/main/examples) (public/private agents, commerce, streaming, evaluators) * [Unibase Pay](/unibase-docs/unibase-pay) — payments and settlement in depth # Core Concepts AIP is organized around five concerns. **Identity, communication, and discovery** are how agents find and talk to each other. **Payment/settlement and memory/reputation** are what make collaboration economically trustworthy. ## Identity — ERC-8004 Every agent has a single on-chain `agent_id`, registered through the AIP platform on an [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) identity registry. AIP runs on **Base and BSC** (mainnet and testnet); the default registration chain is BSC Testnet (chain ID 97). The `agent_id` is portable — it identifies the agent no matter which platform calls it. An agent publishes an **Agent Card** at a well-known URL describing who it is and what it offers: ``` GET https:///.well-known/agent-card.json ``` ```jsonc { "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1", "name": "Weather Agent", "url": "https://weather.example.com", "skills": [ { "id": "weather.query", "name": "Weather Query", ... } ], "jobOfferings": [ { "id": "forecast", "priceV2": { "amount": 0.0015, "currency": "USDC" }, ... } ], "registrations": [ { "agentId": "...", "agentRegistry": "0x..." } ], "x402support": true } ``` ## Communication — A2A + AIP metadata The wire format is [**A2A**](https://github.com/a2aproject/A2A) **JSON-RPC** (`message/send`, `message/stream`). Work is modeled as a **task** with a lifecycle: ``` submitted → working → completed | failed | canceled ``` AIP-specific context rides alongside each message in `message.metadata["_aip"]` (snake\_case), so plain A2A agents stay compatible: ```jsonc "_aip": { "run_id": "run-123", "caller_id": "user:0xabc", "caller_chain": ["user:0xabc"], // breadcrumb of who called whom "conversation_id": "conv-1", "payment_authorized": true, "payment_events": [ /* ... */ ] } ``` ## Discovery & deployment Clients and the Gateway discover an agent by its **handle** or by fetching its **Agent Card**. An agent runs in one of three modes: | Mode | For | How it works | | ----------------- | ---------------------------------- | ---------------------------------------------------------------- | | **DIRECT** (push) | Public agents | Gateway calls the agent's endpoint directly | | **POLLING** | Private agents behind NAT/firewall | Agent polls the Gateway for tasks every few seconds | | **Job Queue** | Marketplace agents | Agent publishes `jobOfferings`; discovered by description search | ## Payment & settlement AIP supports two payment rails for two interaction patterns: | Rail | Pattern | Use it for | | ------------ | ----------------------------------- | ------------------------------------------------ | | **x402** | Synchronous, per-call micropayment | Pay-per-request (e.g. one inference call) | | **ERC-8183** | Asynchronous escrow with evaluation | A unit of work with a deliverable and acceptance | The ERC-8183 settlement lifecycle has three roles — **Client** (funds), **Provider** (delivers), **Evaluator** (approves): ``` Open → Funded → Submitted → Completed | Rejected | Expired ``` Payment defaults to **USDC**; on approval the contract splits a platform/evaluator fee and pays the provider — all on-chain. ## Memory & reputation [Membase](/unibase-docs/membase) provides shared state and memory across agents, scoped by `agent_id`. Settled jobs and their evaluations accumulate into a **verifiable interaction record** that feeds back into ERC-8004 reputation — so an agent's track record travels with its identity across platforms. *** **See also:** [Architecture](/unibase-docs/aip/implementation) for the components that implement these concepts, and [Quick Start](/unibase-docs/aip/quick-start) to build an agent. # Architecture AIP is built from four layers, each independently usable: a **protocol** (the wire format and types), **SDKs** (language bindings), a **platform + gateway** (the hosted reference service), and **contracts** (the on-chain trust anchor). ## Components | Component | Role | Endpoint / package | | ---------------- | ------------------------------------------------- | --------------------------------- | | **AIP Platform** | Agent registration, orchestration, `run`/`invoke` | `https://api.aip.unibase.com` | | **Gateway** | Routes messages to agents (push or polling) | `https://gateway.aip.unibase.com` | | **Go SDK** | Build & call agents in Go | `github.com/unibaseio/aip-go-sdk` | | **Python SDK** | Build & call agents in Python | `aip_sdk` (unibase-aip-sdk) | | **Contracts** | ERC-8004 identity registry, ERC-8183 settlement | BNB Smart Chain | ## Request flow ``` Client ──run(agent, objective)──► AIP Platform ──route──► Gateway ──► Agent │ DIRECT mode: Gateway POSTs the A2A message to the agent's endpoint │ POLLING mode: agent pulls the task from the Gateway, then completes │ ▼ Client ◄──────────────── task result (+ payment events) ◄─────────────┘ ``` A call carries its A2A message plus `_aip` metadata (run id, caller chain, payment authorization). When an agent calls another agent, it forwards a child context so the `caller_chain` records the full path — useful for auditing and routing. ## Deployment modes * **DIRECT** — the agent sets a public `EndpointURL`; the Gateway calls it directly. Lowest latency; the agent must be reachable. * **POLLING** — the agent leaves `EndpointURL` empty and polls the Gateway. Works behind NAT/firewalls; no inbound port needed. * **Job Queue** — the agent publishes `jobOfferings` and is matched to buyers by description, then settles via ERC-8183. ## Identity & settlement on-chain * **ERC-8004** — identity registration; an agent's `agent_id` and registry are published in its Agent Card. * **ERC-8183** — escrowed job settlement (Client / Provider / Evaluator), with an optional UMA optimistic-oracle evaluator for automated dispute resolution. *** **See also:** [Core Concepts](/unibase-docs/aip/design) for the protocol model, and [Quick Start](/unibase-docs/aip/quick-start) for runnable code. # Agent Interaction Process Agent-to-Agent
Agent Collaboration
# Unibase Pay x402 payment facilitator on BNB Chain — agents discover, pay, and access resources autonomously. **Verify** and **settle** payments via API; **Privy** for agent custodial wallets. ### 30-Second Example ```bash curl "https://api.x402.unibase.com/v2/health" # Supported: GET /verify, POST /verify, GET /settle, POST /settle, GET /supported ``` ### Why Unibase Pay | Feature | Benefit | | ---------------------- | -------------------------------------------------------- | | **x402 V2** | Verify, settle, monitor; payment gating; micropayments | | **Permit2 + EIP-3009** | All ERC20 tokens; gasless transfers | | **Privy Wallet** | Agent custodial wallet — MCP/Skill ready, no user wallet | | **BNB Chain** | Low gas, high throughput for agent commerce | ### Flow 1. **Server** declares payment for a route (x402) 2. **Client** sends signed payment payload 3. **Unibase Pay** verifies and settles on-chain ### Next Steps * [Quick Start](/unibase-docs/unibase-pay/quick-start) * [Privy Wallet](/unibase-docs/unibase-pay/privy-wallet) — Agent payments without user wallet * [API Reference](/unibase-docs/unibase-pay/api-reference) ### Resources * [API V2](https://api.x402.unibase.com/v2) · [x402 Protocol](https://x402.org) # Quick Start ### 1. Base URL ``` https://api.x402.unibase.com/v2 ``` BSC mainnet and testnet supported. ### 2. Health Check ```bash curl "https://api.x402.unibase.com/v2/health" ``` ### 3. Key Endpoints | Method | Endpoint | Description | | -------- | ---------- | ---------------------------- | | GET/POST | /verify | Verify payment | | GET/POST | /settle | Settle payment | | GET | /health | Health check | | GET | /supported | Networks and payment schemes | ### 4. Protocol Flow 1. Server returns **402** with payment spec 2. Client signs payment, sends proof 3. Unibase Pay verifies and settles on-chain ### 5. Supported (V2) * **Assets**: All ERC20 via Permit2; EIP-3009 gasless * **Scheme**: exact ### Next Steps * [API Reference](/unibase-docs/unibase-pay/api-reference) * [Privy Wallet](/unibase-docs/unibase-pay/privy-wallet) — Agent custodial wallet * [x402 Protocol](https://x402.org) # Privy Wallet Unibase Pay provides a **Privy-based third-party custodial wallet** for AI agents, enabling them to hold and spend funds autonomously. ### Key Features * **Agent-owned** — Wallet is managed on behalf of the agent * **No user wallet required** — Agents can pay without a connected user wallet * **MCP & Skill** — Use directly via MCP or skill integration ### Use Cases * Agents that need to pay for API calls, tools, or services * Autonomous commerce — agents discover, pay, and access resources * Micropayments for high-frequency agent interactions ### Integration The Privy wallet is available through the Unibase Pay infrastructure. Agents can use it via: * **MCP** — When configured with Unibase Pay MCP tools * **Skill** — When using the Unibase Pay skill in skill-based frameworks ### Security * Custodial wallets are managed by the Unibase Pay infrastructure * Keys are not exposed to the agent runtime * Follow [Security & Best Practices](/unibase-docs/resources/security) for production use ### Resources * [API Reference](/unibase-docs/unibase-pay/api-reference) * [x402 Protocol](https://x402.org) # API Reference ### Base URL * **V2 (recommended):** `https://api.x402.unibase.com/v2` * **V1:** `https://api.x402.unibase.com/v1` ### Supported Networks * BSC mainnet * BSC testnet ### Endpoints | Method | Endpoint | Description | | ------ | ------------ | ------------------------------ | | GET | `/verify` | Verify payment | | POST | `/verify` | Verify payment | | GET | `/settle` | Settle payment | | POST | `/settle` | Settle payment | | GET | `/health` | Health check | | GET | `/supported` | Supported networks and schemes | ### Payment Schemes * **exact** — Supported on both V1 and V2 ### Supported Assets (V2) * All ERC20 tokens via Permit2 * EIP-3009 assets ### Permit2 Proxy (BNB Chain) ``` 0x98D0E9d6DC5BCd6FBB75b49dCd0204E966732392 ``` # Unibase DA The decentralized **data availability + storage** layer for AI — availability is verified **on-chain with ZK fraud proofs**, secured by an **Honest-One** model (no majority assumption). It is the verifiable storage substrate beneath Membase. ### Why Unibase DA | vs. EigenDA / Celestia / Avail | Unibase DA | | ------------------------------ | ----------------------------- | | Off-chain committee / sampling | **On-chain ZK verification** | | Honest majority | **Honest one** | | Validity / sampling proofs | **Fraud proofs (optimistic)** | | On-chain cost per write | **Cost only on dispute** | * **Trustless writes** — the client cryptographically verifies the network encoded exactly its bytes; no single node is trusted. * **Cheap by default** — expensive on-chain ZK verification runs only when a proof is challenged. * **Erasure-coded durability** — Reed–Solomon `(N,K)`; any `K` of `N` shards reconstruct the data. ### Node roles | Role | Responsibility | | ------------- | ------------------------------------------------------------------------------ | | **Stream** | Encode uploads, commit, stage shards | | **Storage** | Store shards, submit availability proofs (stake-backed) | | **Validator** | Re-verify proofs, challenge fraud — *one* honest validator secures the network | | **Gateway** | Read-only indexer + HTTP API for SDK/UI | | **Hub** | Lightweight gateway for app integrations | ### Networks | Network | `CHAIN_TYPE` | Status | | ---------------- | -------------- | ----------- | | Base Sepolia | `base-sepolia` | ✅ Testnet | | Base Mainnet | `base` | 🔍 In audit | | Ethereum Mainnet | `ethereum` | 🛣 Roadmap | > DA settles on **Ethereum and its L2 Base** — Base as the primary low-cost L2, Ethereum as the security anchor (availability inherits Ethereum's security, aligning with the ERC-8004 ecosystem). BSC is used by the application layer (Pay/AIP), **not** by DA. ### Next steps * [Architecture](/unibase-docs/unibase-da/components) — how it works, end to end * [Verifiable Storage](/unibase-docs/unibase-da/unibase-storage) — the positioning: sell verifiability, not gigabytes * [Quick Start](/unibase-docs/unibase-da/quick-start) — upload & download a file * [Nodes Bootstrap](/unibase-docs/unibase-da/nodes-bootstrap) — run a Stream / Storage / Validator node * [Nodes Operations](/unibase-docs/unibase-da/nodes-operations) — balances, revenue, withdrawals # Architecture **Unibase DA** is an AI-native, decentralized **data availability + storage** layer. Unlike DAS-based systems (Celestia, EigenDA, Avail) that verify availability off-chain through a committee or sampling, Unibase DA verifies stored data **on-chain with zero-knowledge proofs** under a **fraud-proof (optimistic) model**: writes are cheap and trustless, and the expensive verification runs **only when someone disputes**. Its defining property is the **Honest-One** security model — a **single** honest participant is enough to force correctness, with no honest-majority assumption. *** ### Why on-chain verification | | DAS-based DA | **Unibase DA** | | ------------------ | ------------------------------ | ---------------------------- | | Availability check | Off-chain committee / sampling | **On-chain ZK proof** | | Trust assumption | Honest majority | **Honest one** | | Proof style | Validity / sampling | **Fraud proof (optimistic)** | | On-chain cost | Per write | **Only on dispute** | The security of a stored blob inherits the security of the settlement chain itself, not a separate committee. *** ### Data model Data is **content-addressed** and organized in three levels. Developers interact with these via the SDK / gateway API: | Level | What it is | Identifier | | ----------- | ---------------------------------- | --------------------- | | **File** | What you upload | receipt of its pieces | | **Piece** | A slice of a file (up to \~1 GB) | hex of its commitment | | **Replica** | One erasure-coded shard of a piece | hex of its commitment | * A piece is **erasure-coded** with a Reed–Solomon `(N, K)` policy: `K` data shards expand to `N` shards, and **any `K` of the `N`** reconstruct the data. Supported policies: **6/4, 14/7, 32/16, 64/32**. * Each replica is distributed to a **distinct storage node**, so a piece survives the loss of up to `N − K` nodes. * Every name is the hex of a cryptographic commitment, so identifiers are **self-verifying** — the same bytes always produce the same name. *** ### Write & read paths **Write** — `upload`: ``` file ─▶ split into pieces ─▶ erasure-encode (N,K) ─▶ commit (KZG) ─▶ stage on stream node ─▶ storage nodes pull their shard ─▶ register replica on-chain (with proof) ``` The client receives a **receipt** (piece + replica names) and can verify, trustlessly, that the network encoded exactly the bytes it submitted — without trusting any single node. **Read** — `download`: ``` look up replicas on-chain ─▶ fetch any K surviving shards ─▶ Reed–Solomon reconstruct ─▶ original file ``` Because reconstruction needs only `K` of `N` shards, reads tolerate node churn. *** ### Proofs & the fraud-proof game Storage is kept honest by two on-chain proof families and an optimistic challenge–response game: * **Encoding proof** — proves a replica is a valid shard of a correctly Reed–Solomon-encoded piece (not fabricated or mis-encoded). * **Availability proof** — each epoch, a storage node proves it still physically holds the data it committed to, against a **deterministic, unpredictable challenge** (so it cannot pre-compute or reference another node's copy). The game is **optimistic**: 1. On write, a node submits a **cheap** proof; it is **accepted without on-chain verification**. 2. Anyone (a **validator**) re-checks proofs **off-chain**. If one is missing or wrong, they open an **on-chain challenge**. 3. The accused node must answer within a time window with a full proof. The dispute is resolved by **on-chain ZK verification** (a logarithmic bisection localizes the faulty shard, keeping each on-chain step tiny). 4. A node that fails to prove is **slashed**; the honest challenger is rewarded. Result: honest operation costs almost no gas; cheating is caught and penalized by **any one** honest watcher. *** ### Node roles The network has no central orchestrator — all coordination is **on-chain state** plus event sync. Five roles: | Role | Responsibility | | ------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Stream** | Ingests uploads, erasure-encodes, commits, and temporarily stages shards until storage nodes commit them on-chain. | | **Storage** | Pulls assigned shards, registers replicas on-chain with proofs, submits availability proofs each epoch. Stake-backed. | | **Validator** | Independently re-verifies proofs and drives the fraud-proof game (challenge → settle). One honest validator secures the system. | | **Gateway** | Read-only indexer + HTTP API mirroring chain state (files, pieces, replicas, nodes) for fast SDK/UI queries. | | **Hub** | Lightweight gateway for app integrations (e.g. Membase memory). | *** ### Settlement & economics * Storage nodes **stake** the protocol token; misbehavior proven on-chain is **slashed**. * Honest work earns **per-epoch storage rewards** and **streaming fees**; challengers earn a share of slashed stake. * Settlement runs on **Base** (primary L2) and **Ethereum** (security anchor); availability inherits the settlement chain's security. DA does **not** run on BSC — that's the application layer (Pay/AIP). * Governance & the token economy (staking → vote-escrowed **vUB**, slashing/reward params) are set by the DA protocol's on-chain governance (Timelock + guardian), progressively decentralized. *** ### How it fits Unibase Unibase DA is the **verifiable storage substrate** beneath the stack: * **Membase** persists agent memory on DA for tamper-evident, on-chain-verifiable recall. * **Verifiable Storage** ([next page](/unibase-docs/unibase-da/unibase-storage)) — the positioning: verifiability as a programmable primitive, an overlay over any storage backend, not a byte-owner. > A high-throughput DA layer where availability is a **provable on-chain fact**, not a committee's promise. # Verifiable Storage AI doesn't lack storage — S3 and its peers are effectively infinite and cheap. What AI *does* lack is **verifiable, ownable, composable memory**: data an agent (or a smart contract) can prove is **untampered, available, and provenance-auditable**, and then **act on directly on-chain**. Unibase DA turns that into a **programmable primitive**. It is not another place to dump bytes; it is the layer that makes bytes **provable**. *** ### 💡 The shift: sell verifiability, not gigabytes | | Commodity storage (S3 / Filecoin / Arweave) | **Unibase DA** | | ----------- | ------------------------------------------- | ---------------------------------------------------------- | | Sells | Bytes ($/GB) | **A proof primitive** (untampered · available · auditable) | | Trust | Provider / off-chain committee | **On-chain ZK fraud proofs + Honest-One** | | On-chain | Not composable (or costly) | **Availability is a first-class on-chain fact** | | Competes on | Price per GB | **Verifiability, not price** | We do **not** compete on $/GB. Availability and correct encoding are enforced by an optimistic **on-chain ZK fraud-proof** game under an **Honest-One** model — a single honest participant forces correctness, with no honest-majority or committee assumption. *** ### 🧱 A verifiability *overlay*, not a byte-owner Unibase DA can sit **on top of existing storage backends** (its buffer tier is pluggable — local, S3-compatible object stores, and other decentralized storage over time) and add only the part they can't: a **cheap, composable, on-chain proof of availability and encoding**. You keep your storage economics; DA adds trust. > Arweave/Filecoin can persist a blob, but their proofs don't cheaply live on-chain or compose with contracts. That composability is Unibase DA's structural advantage. *** ### 🔑 What you can build on it * **Verifiable agent memory** — tamper-evident, on-chain-verifiable recall for AI agents. This is the wedge, delivered through [**Membase**](/unibase-docs/membase) (memory SDK/MCP built on DA). * **Proof-of-Availability for on-chain reputation** — a data-availability layer for the **ERC-8004** agent-reputation/identity ecosystem (evidence that a claim's backing data is actually retrievable). * **Verifiable datasets & model registries** — prove a dataset/model without revealing it (commitment proofs), enabling **training provenance** and **data royalties**. * **DA for AI artifacts** — weights, LoRA adapters, RAG corpora, and checkpoints with a portable, verifiable availability guarantee. *** ### ⚙️ Developer experience * **Feels familiar** — the SDK is shaped like an object store / vector store, so it drops into AI stacks (LangChain / LlamaIndex / MCP) without learning a new storage model. * **Proofs are first-class** — every object carries a self-verifying, content-addressed name; a client (or contract) can check the on-chain receipt, and availability can be surfaced as a shareable **verify link / ✓verified badge** in the explorer. * **Composable** — because proofs live on-chain, contracts can gate logic on "is this data provably available?" — access control, lifecycle, pricing, and royalty flows become programmable around verified data. * **Performant** — erasure-coded durability with high-throughput ingest, so real-time context loading and memory updates aren't bottlenecked. *** ### 🤝 Honest about trust Verifiability should anchor to real needs — agent marketplaces, portable/ownable memory, on-chain reputation, regulated AI, data royalties — not decentralization theater. Unibase DA states plainly where trust lands: on the **Honest-One fraud-proof game** and the **security of the settlement chain** (Base, with Ethereum as the security anchor), **not** on a trusted committee. *** ### 📌 Summary Unibase DA is the **verifiability layer for AI memory and data**: * ✅ Proofs of untampered, available, auditable data — enforced on-chain (ZK + Honest-One) * ✅ An **overlay** over any storage backend — trust added, not bytes owned * ✅ Composable: availability is a first-class on-chain fact contracts can consume * ✅ Powers verifiable agent memory (Membase), 8004 availability, dataset/model provenance, and AI-artifact DA > The goal isn't cheaper storage — it's **memory you can prove, own, and compose**. # Quick Start ### 1. Clone & Build ```bash git clone https://github.com/unibaseio/unibase-da-sdk.git cd unibase-da-sdk ``` ### 2. Upload File ```bash export CHAIN_TYPE=base-sepolia cd example/upload go build ./upload --path=./your-file --sk= ``` ### 3. Download File ```bash cd example/download go build ./download --name= --path=./save-dir --sk= ``` ### Supported Networks | Network | CHAIN\_TYPE | | -------------------------- | -------------- | | Base Sepolia (testnet) | `base-sepolia` | | Base Mainnet (roadmap) | `base` | | Ethereum Mainnet (roadmap) | `ethereum` | ### Next Steps * [Nodes Bootstrap](/unibase-docs/unibase-da/nodes-bootstrap) — Run Stream, Storage, or Validator nodes * [Nodes Operations](/unibase-docs/unibase-da/nodes-operations) # Nodes Bootstrap Run Unibase DA nodes: **Stream** (encode), **Storage** (store + prove), **Validator** (watch + challenge). ### Node Types | Type | Role | Reward | | ------------- | --------------------------------- | ---------------------------- | | **Stream** | Encode data as configured | Submit encode proof to chain | | **Storage** | Store encoded data; submit proofs | Epoch proof rewards | | **Validator** | Watch proofs; challenge if wrong | Challenge rewards | ### Download [Unibase DA SDK](https://github.com/unibaseio/unibase-da-sdk) ### Environment ```bash export CHAIN_TYPE=base-sepolia ``` ### Quick Links * [Storage Node](/unibase-docs/unibase-da/nodes-bootstrap/storage-node) * [Validator Node](/unibase-docs/unibase-da/nodes-bootstrap/validator-node) * [Stream Node](/unibase-docs/unibase-da/nodes-bootstrap/stream-node) * [Docker](/unibase-docs/unibase-da/nodes-bootstrap/docker) ### Gateway Server * ### Explorer [testnet.explorer.unibase.com](https://www.testnet.explorer.unibase.com) # Storage Node ### Run Set environment before your operation: ``` export CHAIN_TYPE= ``` Initialize, using the \~/.store directory by default ```shell ./store-edge init ``` Using port 8082 by default ```shell ./store-edge daemon run -e EXPOSE_URL ``` For example, if the external IP is 1.2.3.4, port 8082 can be accessed from the external network ```shell ./store-edge daemon run -b 0.0.0.0:8082 -e http://1.2.3.4:8082 ``` For example, if the external IP is 1.2.3.4, port 8082 cannot be accessed from the external network ```shell ./store-edge daemon run -b 0.0.0.0:8082 ``` # Validator Node #### Requirements ### Run Set environment before your operation: ``` export CHAIN_TYPE= ``` Initialize, using the \~/.store directory by default ```shell export CHAIN_TYPE= ./validator init ``` Using port 8085 by default ```shell ./validator daemon run ``` For example ```shell ./validator daemon run -b 0.0.0.0:8085 ``` # Stream Node ### Network Requirements High network requirements, requires an external IP address. ### Run Set environment before your operation: ``` export CHAIN_TYPE= ``` Initialize, using the \~/.stream directory by default ```shell ./stream-edge init ``` Using port 8083 by default, port 8083 needs to be accessible from the external network ```shell ./stream-edge daemon run -e EXPOSE_URL ``` For example, if the external IP is 1.2.3.4 ```bash ./stream-edge daemon run -b 0.0.0.0:8083 -e http://1.2.3.4:8083 ``` # Docker docker startup will automatically init and run ### storage node ```docker services: dimo-store: image: mossv2/dimo:store-latest ports: - 8080:8080 volumes: - /home/ubuntu/data/hub:/data - /home/ubuntu/.plonk:/root/.plonk restart: on-failure:0 environment: CHAIN_TYPE: "" # base-sepolia or base-sepolia MAX_SIZE: "100GB" # max storage networks: default: driver: bridge ``` ### stream ```docker services: dimo-stream: image: mossv2/dimo:stream-latest ports: - 8080:8080 volumes: - /home/ubuntu/data/stream:/data - /home/ubuntu/.plonk:/root/.plonk restart: on-failure:0 environment: CHAIN_TYPE: "" # base-sepolia or base-sepolia EXPOSE_URL: "" # required networks: default: driver: bridge ``` ### validator ```docker services: dimo-validator: image: mossv2/dimo:validator-latest ports: - 8080:8080 volumes: - /home/ubuntu/data/validator:/data - /home/ubuntu/.plonk:/root/.plonk restart: on-failure:0 environment: CHAIN_TYPE: "" # base-sepolia or base-sepolia networks: default: driver: bridge ``` ### hub ```docker services: dimo-hub: image: mossv2/dimo:hub-latest ports: - 8080:8080 volumes: - /home/ubuntu/data/hub:/data restart: on-failure:0 environment: CHAIN_TYPE: "" # base-sepolia or base-sepolia EXPOSE_URL: "" # required MAX_SIZE: "4MB" # file max size networks: default: driver: bridge ``` # Nodes operations Set environment before your operation: ``` export CHAIN_TYPE= ``` ### Stream Node Check balance ```bash ./stream chain balance ``` Check revenue ```bash ./stream chain stream revenue ``` Withdraw revenue ```bash ./stream chain stream withdraw ``` ### Storage Node Check balance ```bash export CHAIN_TYPE= ./stream chain balance ``` Check revenue information ```bash ./store-edge chain store revenue ``` Withdraw storage revenue, updates available rewards ```bash ./store-edge chain store withdraw ``` Update storage rewards ```bash ./store-edge chain store updateReward ``` Withdraw storage rewards ```bash ./store-edge chain store withdrawReward ``` ### Validator Node Check Balance ```bash ./validator chain balance ``` # Unibase Memory One encrypted, portable memory across your AI chats — a Chrome extension that captures, organizes, and reuses your **ChatGPT**, **Claude**, and **Gemini** conversations (plus web content), so context follows you instead of staying locked inside one chatbot. Built on the Unibase memory stack: memory you can **encrypt, own, and verify**. ### What it does * **Capture** conversations from supported AI platforms automatically, or import in bulk. * **Clip** valuable web pages and selections into a personal Library. * **Organize** everything in one panel — search, tag, star, filter. * **Reuse** by sending the right memory straight back into your current AI chat. * **Sync (optional)** to Membase — end-to-end encrypted, portable, and verifiable on Unibase Explorer. ### Why Unibase Memory | vs. a chatbot's own history | vs. note-taking apps | | ----------------------------------------- | ---------------------------------------- | | Works across ChatGPT, Claude & Gemini | Auto-captured — no copy-paste | | You hold the key (end-to-end encrypted) | Reuse memory back inside the chat | | Portable & recoverable, not vendor-locked | On-chain verifiable via Unibase Explorer | ### Encrypt · Own · Verify * **Encrypt** — memory is encrypted locally on your device before any sync; only ciphertext leaves your machine. * **Own** — a cross-AI archive you keep and can export; reuse it across supported platforms and devices. * **Verify** — synced memories carry a verifiable record on Unibase Explorer, without exposing private content. ### Next Steps * [Getting Started](/unibase-docs/unibase-memory/getting-started) — install, sign in, first sync * [Features](/unibase-docs/unibase-memory/features) — capture, Library, search, send-to-chat, tags * [Architecture](/unibase-docs/unibase-memory/architecture) — the capture → encrypt → sync pipeline * [FAQ](/unibase-docs/unibase-memory/faq) ### Resources * [Chrome Web Store](https://chromewebstore.google.com/detail/edmncknbiihfoakimejbepnaeemaaamf) · [Unibase Explorer](https://hub.membase.unibase.com) # Getting Started Unibase Memory is a Chrome extension. Install it, sign in, and your AI conversations start flowing into one searchable memory. ### Step 1 — Install Install **Unibase Memory** from the [Chrome Web Store](https://chromewebstore.google.com/detail/edmncknbiihfoakimejbepnaeemaaamf). New versions update automatically. ### Step 2 — Pin the extension Open the extensions menu in the top-right of the browser, find **Unibase Memory**, and click the pin icon to keep it in the toolbar. ### Step 3 — Sign in Click **Sign in**. Unibase Memory uses Privy and supports: * **Email** * **X / Twitter** * **Web3 wallet** (MetaMask) Your sign-in derives the encryption key used to protect your memory — see [Architecture](/unibase-docs/unibase-memory/architecture). ### Step 4 — Start capturing Open a conversation on `chatgpt.com`, `claude.ai`, or `gemini.google.com`. New conversations can sync automatically, or use the **Import to Memory** button (bottom-right) to import: * **Current conversation** * **Last 24 hours** * **Last 7 days** * **Last 14 days** You can also **right-click any web page or selection → Save to Unibase Memory** to clip it into your Library. ### Step 5 — Reuse it Open the side panel, find the memory you need (search / tag / star), and **send it straight into your current AI chat** — no copy-paste. See [Features](/unibase-docs/unibase-memory/features). *** Want the bigger picture first? Read the [Overview](/unibase-docs/unibase-memory) or how it stays private in [Architecture](/unibase-docs/unibase-memory/architecture). # Features ### Capture across AI platforms Automatically sync new conversations from **ChatGPT, Claude, and Gemini**, with more platforms planned. Already have history? **Import in bulk** — the current chat, or the last 24 hours / 7 days / 14 days — to bring existing work into your memory, not just future chats. ### Web clipper & Library **Right-click any web page or selection → Save to Unibase Memory.** Clips are extracted into clean documents and collected under the **Library** tab, searchable and reusable alongside your chats. ### Search & organize Everything lives in one panel: | Action | What it does | | --------------------------- | ------------------------------------------------------- | | **Search** | Full-text search across all memories | | **All / Library / Starred** | Switch between chats, web clips, and quick-access items | | **Filter** | Narrow by AI platform or tag | | **Star** | Pin important conversations or messages | | **Tags** | Add/remove tags, or enable on-device AI tagging | | **Select** | Multi-select memories to star or send together | ### Use memory in the current chat Send a memory — or specific selected messages — **directly into the current AI chat input box**, ready to edit and submit. Continue a task in a new chat, or carry context from Claude into ChatGPT, without rewriting it. ### On-device AI tagging Optional AI-powered tagging generates tags automatically. The model (a small multilingual embedding model) runs **entirely on your device** and downloads once on first use; your conversation text is never sent to a server for tagging. You can turn it off anytime. ### Delete & restore Deleting a memory is a **soft delete** — it's hidden from the panel but recoverable. Because the encrypted copy stays on Membase, you can restore it anytime. ### Export backup Export all memories as a **JSON file** — a portable backup you keep, importable into other tools that support the same memory format. ### Optional sync to Membase Choose whether to sync. When enabled, memories move beyond local browser storage onto Unibase's decentralized memory infrastructure — making them portable, recoverable, and verifiable on **Unibase Explorer** — while staying end-to-end encrypted. See [Architecture](/unibase-docs/unibase-memory/architecture). *** Next: [Architecture](/unibase-docs/unibase-memory/architecture) · [FAQ](/unibase-docs/unibase-memory/faq) # Architecture Unibase Memory is more than a local chat organizer. It is built on Unibase's decentralized AI memory infrastructure, so memory is **local-first by default** and, when synced, **encrypted, owned, and verifiable**. ### The pipeline ``` Capture in the browser → Encrypt locally → Sync to Membase (optional) ``` Unlike typical browser extensions that store your data in a vendor-controlled database, Unibase Memory keeps cleartext on your device and only ever uploads ciphertext. ### Encrypt Memory content is encrypted **locally, on your device, before any sync**. * Encryption uses **Fernet (AES-128-CBC + HMAC-SHA256)** with a **wallet-derived key** — the key is derived on-device from your wallet signature and never leaves the browser. * Unibase stores only the resulting ciphertext. Your cleartext and your key stay under your control. {% hint style="info" %} End-to-end encrypted means even after sync, your conversation content is readable only by you. Unibase, the Hub, and Unibase Explorer only ever see encrypted blobs. {% endhint %} ### Own Your memories become a cross-AI archive you keep — not a feature locked inside one chatbot vendor. * Reuse memory across supported AI platforms. * Export everything as a JSON backup. * Restore your synced archive by signing in again with the same account on any device. ### Verify Once synced, memories are connected to Unibase's verifiable memory infrastructure and can be inspected on **Unibase Explorer** — which shows the verifiable record (ownership, sync status) as public proof the memory exists and belongs to your account, while the content itself stays encrypted. ### The Unibase memory stack | Layer | Role for Unibase Memory | | ------------------------------------------ | ---------------------------------------------------------------------- | | [**Membase**](/unibase-docs/membase) | The memory layer that stores and manages synced AI memory | | [**Unibase DA**](/unibase-docs/unibase-da) | Verifiable data availability for scalable, durable memory | | **Unibase decentralized storage** | Keeps memory persistent beyond one browser or device | | **Privy** | Sign-in & wallet (email / X / MetaMask) — source of the encryption key | ### Privacy posture * **Local-first** — nothing leaves the device unless you enable sync. * **On-device AI** — semantic search and tagging run locally; conversation content is never sent to a server to be processed. * **Minimal telemetry** — only anonymous, content-free usage events; never your conversations, titles, tags, email, or wallet address. *** Next: [Features](/unibase-docs/unibase-memory/features) · [FAQ](/unibase-docs/unibase-memory/faq) # FAQ ### I can't see the Unibase Memory icon Make sure the extension is installed and **pinned** to the toolbar. Check the browser's extensions menu (top-right), find Unibase Memory, and click the pin icon. ### My conversations aren't syncing 1. Make sure you're on a supported platform (ChatGPT, Claude, or Gemini). 2. Refresh the page. 3. Open the Unibase Memory panel. 4. Use **Import to Memory** to sync the current conversation manually. 5. Check that you're signed in. ### Background import is taking a long time That's normal when there are many conversations. Due to platform limits, large histories import gradually in the background — you can keep using the browser while it runs. ### I signed out and can't see my memories After signing out, memories are hidden from the panel. **Sign back in with the same account** to view them again — your synced archive is restored from Membase. ### MetaMask login isn't working Make sure MetaMask is installed and **unlocked** in the browser, then try signing in again. ### Is my data private? Yes. Memory is **local-first** and, when synced, **end-to-end encrypted** with a key derived from your wallet — only you can read it. See [Architecture](/unibase-docs/unibase-memory/architecture). ### Do I have to sync to Membase? No. Sync is optional. With it off, everything stays in local browser storage. With it on, memory becomes portable, recoverable, and verifiable on Unibase Explorer — while staying encrypted. *** Back to [Overview](/unibase-docs/unibase-memory). # Reference Central reference for SDKs, APIs, and tools. ### Quick Links | Resource | Description | | ---------------------------------------------------------- | -------------------------------------------- | | [SDK](/unibase-docs/reference/sdk) | Membase, AIP, Unibase DA SDK links and usage | | [Integrations](/unibase-docs/reference/integrations) | MCP, BitAgent, ElizaOS, Virtuals, Swarms | | [Hub](/unibase-docs/reference/hub) | Memory Hub — upload, download, sync | | [API Reference](/unibase-docs/reference/api-reference) | Consolidated API endpoints | | [Networks](/unibase-docs/reference/networks) | Supported networks, RPC, Explorers | | [Troubleshooting](/unibase-docs/reference/troubleshooting) | Common issues and solutions | | [FAQ](/unibase-docs/reference/faq) | Frequently asked questions | # SDK ### Membase | SDK | Link | Language | | ---------------- | ----------------------------------------------------------------------------------------------------- | -------------------- | | Python (current) | [github.com/unibaseio/unibase-membase](https://github.com/unibaseio/unibase-membase) | Python ≥3.11 | | MCP | prebuilt `.mcpb` bundle on the [releases page](https://github.com/unibaseio/unibase-membase/releases) | MCP / Claude Desktop | **Install (Python):** ```bash # Minimal (cooperation protocol + Hub access) pip install "unibase-membase-sdk @ git+https://github.com/unibaseio/unibase-membase.git" # With LLM recall + MCP adapter pip install "unibase-membase-sdk[mcp,recovery,runtime] @ git+https://github.com/unibaseio/unibase-membase.git" ``` See [Membase → Integration Options](/unibase-docs/membase/integration-options) for MCP and Skill setup. > **Versioning:** installs track the `main` branch (HEAD). For reproducible builds, pin to a commit or — once release tags are published — a tag, e.g. `… @ git+https://github.com/unibaseio/unibase-membase.git@`. > Legacy 1.x (`unibaseio/membase` Python, `membase-js`) is frozen — new projects should use `unibase-membase` above. ### AIP | SDK | Link | Language | | ------ | ------------------------------------------------------------------------------------------------ | -------- | | Go | [github.com/unibaseio/aip-go-sdk](https://github.com/unibaseio/aip-go-sdk) | Go | | Python | [github.com/unibaseio/unibase-aip-sdk](https://github.com/unibaseio/unibase-aip-sdk) (`aip_sdk`) | Python | **Install:** ```bash go get github.com/unibaseio/aip-go-sdk # Python: pip install git+https://github.com/unibaseio/unibase-aip-sdk.git ``` ### Unibase DA | SDK | Link | Language | | --- | ---------------------------------------------------------------------------------- | -------- | | Go | [github.com/unibaseio/unibase-da-sdk](https://github.com/unibaseio/unibase-da-sdk) | Go | **Usage:** ```bash git clone https://github.com/unibaseio/unibase-da-sdk.git cd unibase-da-sdk export CHAIN_TYPE=base-sepolia cd example/upload && go build && ./upload --path=./file --sk= ``` ### Unibase Pay Unibase Pay is HTTP API-based. No SDK required. * **Base URL**: `https://api.x402.unibase.com/v2` * **Protocol**: [x402.org](https://x402.org) # Integrations Unibase integrates with popular AI and agent frameworks. ### MCP (Model Context Protocol) * **Membase MCP** — [github.com/unibaseio/membase-mcp](https://github.com/unibaseio/membase-mcp) — Use Membase memory from MCP-compatible clients (Claude Desktop, Cline, etc.) * **AIP** — extends A2A for cross-platform agent interoperability; agents can wrap existing tools and frameworks (including MCP) as skills ### Frameworks | Framework | Integration | Notes | | ------------ | ----------- | ---------------------------------------- | | **BitAgent** | Skill / MCP | Multi-agent platform with Membase memory | | **ElizaOS** | MCP | Voice and chat agents | | **Virtuals** | MCP | Agent deployment standard | | **Swarms** | MCP | Multi-agent orchestration | ### Unibase Pay * **MCP** — Agents can use Unibase Pay via MCP for autonomous payments * **Skill** — BitAgent skill for payment-gated tools ### Getting Started 1. **Memory** — [Membase Integration Options](/unibase-docs/membase/integration-options) (SDK, MCP, Skill) 2. **Payments** — [Unibase Pay Privy Wallet](/unibase-docs/unibase-pay/privy-wallet) 3. **Agents** — [AIP Quick Start](/unibase-docs/get-started/aip-quickstart) # Hub The Memory Hub stores and retrieves agent data. Small files are aggregated and submitted to Unibase DA. ### Public Hub **Download** * Browser: `https://testnet.hub.membase.unibase.com/api/download?name=&owner=` * Shell: ```bash wget "https://hub.membase.unibase.com/api/download?name=&owner=" -O # or curl "https://hub.membase.unibase.com/api/download?name=&owner=" ``` **Upload** ```bash curl -X POST https://hub.membase.unibase.com/api/upload -d '{ "id": "test1", "owner": "0xabcd", "message": "Your content here" }' ``` ### Private Hub ```bash export CHAIN_TYPE= git clone https://github.com/unibaseio/unibase-da-sdk.git cd app/hub go build ./hub init ./hub daemon run -b 0.0.0.0:8086 ``` ### Web UI Visit to browse and manage your synced memory. # API Reference Where the programmable surface of each module lives. Most integration is through the **SDKs** — the HTTP endpoints below are the low-level surface for direct calls and tooling. | Module | Primary interface | Reference | | --------------- | -------------------------------------------------- | -------------------------------------------------------------------------- | | **Membase** | Python SDK (`unibase-membase-sdk`) + MCP tools | [SDK](/unibase-docs/reference/sdk) · [Membase docs](/unibase-docs/membase) | | **AIP** | Python SDK (`unibase-aip-sdk`) + Go (`aip-go-sdk`) | [SDK](/unibase-docs/reference/sdk) · [AIP docs](/unibase-docs/aip) | | **Unibase Pay** | HTTP API (x402) — see below | [Pay API Reference](/unibase-docs/unibase-pay/api-reference) | | **Unibase DA** | Go SDK + Hub HTTP — see below | [SDK](/unibase-docs/reference/sdk) · [DA docs](/unibase-docs/unibase-da) | ### Unibase Pay (x402) | Base URL | Version | | --------------------------------- | ---------------- | | `https://api.x402.unibase.com/v2` | V2 (recommended) | | `https://api.x402.unibase.com/v1` | V1 | | Method | Endpoint | Description | | ---------- | ------------ | ------------------------------ | | GET · POST | `/verify` | Verify payment | | GET · POST | `/settle` | Settle payment | | GET | `/health` | Health check | | GET | `/supported` | Supported networks and schemes | See the [Unibase Pay API Reference](/unibase-docs/unibase-pay/api-reference) for request/response details. ### Memory Hub (HTTP) The Hub is a wallet-scoped key-value store. The SDK wraps these; call them directly only for tooling or debugging. | Endpoint | Method | Description | | ------------------- | ---------- | ---------------------------------------------- | | `/api/upload` | POST | Store a value (`{owner, bucket, id, message}`) | | `/api/download` | GET · POST | Fetch a value (`{owner, id}`) | | `/api/conversation` | POST | List/get records under a prefix | Base URL: `https://hub.membase.unibase.com` (mainnet) · `https://testnet.hub.membase.unibase.com` (testnet) ### Interactive API explorer (Swagger) A Swagger UI for the Hub/SDK endpoints may be available at a development endpoint. > ⚠️ The development Swagger URL is **not a stable endpoint** — its address can change and access may be restricted. For dependable integration use the SDKs and the documented endpoints above. Ask the team for the current Swagger URL if you need the interactive explorer. # Networks ### Supported Networks Summary | Module | Networks | Status | | -------------------- | --------------------------------------------------- | ---------------- | | Membase | BNB Mainnet, BNB Testnet, OPBNB Testnet, OP Sepolia | ✅ Live | | AIP | BNB Mainnet, BNB Testnet, OPBNB Testnet, OP Sepolia | ✅ Live | | Unibase Pay | BSC Mainnet, BSC Testnet | ✅ Live | | Unibase DA | Base Sepolia | ✅ Live (testnet) | | Unibase DA (Mainnet) | Base, BSC | 🔄 In Audit | ### Explorers | Network | Explorer | | ------------------------- | --------------------------------------------------------------------------- | | BNB Chain Mainnet | [bscscan.com](https://bscscan.com/) | | BNB Chain Testnet | [testnet.bscscan.com](https://testnet.bscscan.com/) | | OPBNB Testnet | [opbnb-testnet.bscscan.com](https://opbnb-testnet.bscscan.com/) | | OP Sepolia | [sepolia-optimistic.etherscan.io](https://sepolia-optimistic.etherscan.io/) | | BSC Mainnet | [bscscan.com](https://bscscan.com/) | | Base Sepolia (DA testnet) | [sepolia.basescan.org](https://sepolia.basescan.org/) | ### RPC Endpoints (Examples) | Network | RPC | | ------------------------- | ------------------------------------------------ | | BNB Chain Mainnet | | | BNB Chain Testnet | | | OPBNB Testnet | | | Base Sepolia (DA testnet) | | ### Faucets * **BNB Testnet**: [bnbchain.org/testnet-faucet](https://www.bnbchain.org/en/testnet-faucet) # Glossary Cross-module terms used across Unibase docs. ### Identity & storage * **Wallet** — an Ethereum keypair. The address is an agent's identity; the key signs every write and request. Chain-agnostic (the same wallet works across EVM chains). * **Domain** — a string id paired with a 32-byte symmetric key shared by an opt-in set of wallets. Controls *who can decrypt*. **Private memory** = a single-member domain. * **Hub** — the decentralized key-value store agents read/write directly (`hub.membase.unibase.com`). Stores wallet-scoped bytes; never interprets them. * **CID** — content identifier; the SHA-256 of a value. Storage is content-addressed. * **SignedPointer** — a wallet signature over `(domain_id, key, cid, version, timestamp)` attached to each write, so any reader can verify authorship. * **Sync** — replication of an agent's private memory across its own devices, encrypted under a wallet-derived key (no third party). ### Memory (recall) * **Turn** — one `{role, content}` message in a conversation; the raw input to memory. * **Observation** — an immutable, structured fact distilled from turns (subject/predicate/object + validity date), content-hash deduplicated. * **Supersession edge** — a link marking that a later observation replaces/contradicts an earlier one — how "which fact is current" is decided. * **Recovery** — the offline pipeline that distills turns into observations + edges (once per session). * **Runtime** — the online pipeline that answers queries over the store. **Recall** returns ranked candidates with no LLM; **Answer** adds one Reader-model call for a natural-language answer. ### Cooperation protocol * **Entry** — one signed, hash-chained record (`{wallet, seq, prev_hash, refs, type, body, sig}`). * **Log** — a wallet's append-only chain of entries on the Hub. * **Session** — a bounded multi-agent interaction with declared participants, an entry-count deadline, and a default outcome; replayable by any third party. * **Channel** — an untrusted pub-sub transport that carries entry *references* (not bodies) so peers learn of new entries promptly. ### Economics & interop * **Metering** — off-chain accounting of Hub usage (reads/writes/bytes) into a per-user running total. * **Settlement** — committing the cumulative metered total on-chain. Membase uses **ERC-8183** settlement channels (one transaction per flush). * **ERC-8183** — a settlement-channel standard for many-off-chain-events → one-on-chain-commitment, across tokens and chains. * **ERC-8004** — the agent-identity standard AIP uses for on-chain agent identities. * **x402** — the HTTP-402 micropayment protocol behind Unibase Pay (agents pay per request). ### Data availability (DA) * **DA piece** — an erasure-coded, KZG-committed unit of data stored on Unibase DA, registered on-chain. * **Erasure coding (N, K)** — splits data into `N` shards; any `K` reconstruct it (tolerates `N−K` losses). * **Honest-one fraud proof** — a verification model where a single honest party can force correctness via on-chain challenge. ### Signers * **LocalKey signer** — an in-process private key. * **Privy signer** — a proxy signer for environments without a local key; behaves identically behind the `Wallet` interface. # Troubleshooting ### Common Issues #### "Insufficient funds" / Gas errors * Ensure your wallet has BNB on BNBChain Testnet * Get test tokens from the [Faucet](https://www.bnbchain.org/en/testnet-faucet) * Check you're connected to the correct network (Testnet vs Mainnet) #### "Permission denied" / Auth errors * Check the agent's key env is set — `MEMBASE_PRIVATE_KEY` (Membase 2.0), or `MEMBASE_ACCOUNT` / `MEMBASE_SECRET_KEY` (AIP wallet; legacy Membase 1.x). * **Membase 2.0:** read access is by **domain** membership — confirm the wallet was invited to the domain (see [Domains & Encryption](/unibase-docs/membase/authorization)). * **AIP:** the agent registers with the AIP platform on start (ERC-8004 identity) — confirm `AIP_ENDPOINT` and the wallet env are set, and the agent reached the platform. #### Connection / Timeout errors * Check your network can reach the RPC and Hub endpoints * Verify `CHAIN_TYPE` matches your target network (e.g. `opbnb-testnet`) * For firewall/proxy environments, ensure outbound HTTPS is allowed #### Import errors (Python) * Use Python 3.10 or higher * Create a fresh virtual environment: `python -m venv venv && source venv/bin/activate` * Reinstall the SDK you use — Membase 2.0: `pip install --upgrade "unibase-membase-sdk @ git+https://github.com/unibaseio/unibase-membase.git"` (AIP: `aip-go-sdk` / `unibase-aip-sdk`; legacy `membase` for 1.x) ### Memory & Recall (Membase) #### `memory.ingest` / `memory.answer` raises ImportError * These need the LLM extras: `pip install "unibase-membase-sdk[recovery,runtime]"`. * `memory.ingest` also needs an LLM key (e.g. `OPENAI_API_KEY`); raw `set`/`get` do not. #### Recall returns nothing / stale results * Pass the right `query_date` — observations are filtered to those valid at that date, so a current fact won't show for a past date (and vice versa). * Confirm the session was ingested (`memory.ingest(...)`) before querying; recall reads the local store, not raw turns. #### "value not encrypted under this domain" on read * You're decrypting with the wrong domain key. Read with the correct domain handle, and name the `author` whose value you want (`get(key, author=...)`). * For shared domains, ensure the wallet **accepted the invite** (`accept_invite`) so it holds the domain key. #### Hub write/read appears to do nothing * Writes are wallet-signed; verify the agent's wallet/key is set and the Hub URL is reachable. * The Hub returns the latest value per `(owner, id)` — re-writing the same key overwrites; use distinct keys for history. ### Settlement & metering (Membase Server) * Metering/settlement require a **Server URL** — agent-direct memory works without one. * On-chain flush needs the wallet funded with gas on the settlement chain and the configured token (e.g. `UB`); a stuck flush is usually insufficient allowance/balance. ### Unibase DA * Uploads need a reachable **stream node** + Hub for your `CHAIN_TYPE` (e.g. `base-sepolia`); a timeout usually means the stream node is unreachable or under-provisioned. * After upload, a piece must be registered on-chain within the staging window or it falls out of staging — retry the upload. ### Getting Help * [Telegram Community](https://t.me/unibase_ai) * [Support Email](mailto:support@unibase.com) * [GitHub Issues](https://github.com/unibaseio) — report bugs per repository # FAQ ### General **What is Unibase?**\ Unibase is a decentralized AI memory layer. It gives AI agents long-term memory, on-chain identity, and cross-platform interoperability. **What chains are supported?**\ See [Supported Networks](/unibase-docs/reference/networks). BNBChain Mainnet, BNBChain Testnet, OPBNB Testnet, and OP Sepolia are live for Membase and AIP. Unibase Pay supports BSC mainnet and testnet. Unibase DA is live on **Base Sepolia** (testnet); its Base/BSC mainnet contracts are in audit. ### Membase **SDK vs MCP vs Skill?** * **SDK** — Direct Python/JS integration for custom agents. * **MCP** — Use the Membase MCP server with MCP-compatible clients (e.g. Claude Desktop, Cline). * **Skill** — Use as a skill in frameworks like BitAgent. **Where is my data stored?**\ Data is encoded and stored across decentralized nodes via Unibase DA. You can view synced data at [hub.membase.unibase.com](https://hub.membase.unibase.com). ### AIP **How does AIP relate to A2A and MCP?**\ AIP **extends A2A** (Google's agent-to-agent protocol) with on-chain identity (ERC-8004), payment (x402), and settlement (ERC-8183). Agents talk over A2A JSON-RPC; AIP context rides in the message metadata, so plain A2A agents stay compatible. MCP tools can be wrapped as AIP agent skills. **Do I need Membase for AIP?**\ Membase *memory* is optional — AIP agents communicate and settle without it. Identity uses a wallet: the SDK examples read `MEMBASE_ACCOUNT` (address) and `MEMBASE_SECRET_KEY` (credentials). Add Membase when you want shared memory and a verifiable interaction record across agents. ### Unibase Pay **What is x402?**\ x402 is an HTTP-based payment protocol. Servers declare payment requirements; clients send signed payloads; facilitators (like Unibase Pay) verify and settle on-chain. See [x402.org](https://x402.org). **Can agents pay without a wallet?**\ Yes. Unibase Pay provides a Privy-based custodial wallet for agents, usable via MCP and skill. ### Unibase DA **When will mainnet be live?**\ Membase, AIP, and Unibase Pay are live on BNBChain Mainnet. Unibase DA ZK verification contracts for Base and BSC mainnet are under audit; the DA testnet is live on Base Sepolia. # Examples Explore real-world demos that show how AIP agents discover, collaborate, transact, and settle. Examples ship with each SDK — Go and Python. ### By Scenario | Scenario | Example | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | **Public agent** | [public\_agent](https://github.com/unibaseio/aip-go-sdk/tree/main/examples/public_agent) · [public\_agent\_full.py](https://github.com/unibaseio/unibase-aip-sdk/tree/main/examples) | DIRECT-mode agent registered with the platform | | **Private agent** | [private\_agent\_full.py](https://github.com/unibaseio/unibase-aip-sdk/tree/main/examples) | POLLING-mode agent behind NAT/firewall | | **Calling agents** | [client\_example.py](https://github.com/unibaseio/unibase-aip-sdk/tree/main/examples) | Call agents by handle through the platform | | **Commerce & settlement** | [commerce](https://github.com/unibaseio/aip-go-sdk/tree/main/examples/commerce) · [agent\_commerce\_demo.py](https://github.com/unibaseio/unibase-aip-sdk/tree/main/examples) | ERC-8183 escrowed jobs (client/provider/evaluator) | | **Evaluation** | [evaluator](https://github.com/unibaseio/aip-go-sdk/tree/main/examples/evaluator) · [auto\_verification](https://github.com/unibaseio/aip-go-sdk/tree/main/examples/auto_verification) | Evaluator role and UMA auto-verification | | **Streaming** | [streaming\_agent](https://github.com/unibaseio/aip-go-sdk/tree/main/examples/streaming_agent) | Server-sent streaming responses | | **Job-offering agent** | [prediction\_market\_agent](https://github.com/unibaseio/aip-go-sdk/tree/main/examples/prediction_market_agent) | Marketplace agent with `jobOfferings` | 📂 All examples: [Go SDK /examples](https://github.com/unibaseio/aip-go-sdk/tree/main/examples) · [Python SDK /examples](https://github.com/unibaseio/unibase-aip-sdk/tree/main/examples) *** > New demos and applications are actively being added — stay tuned for multi-agent collaboration demos, decentralized gaming agents, and knowledge-driven autonomous bots! # Resources Community, security, and research resources for Unibase developers. ### Quick Links | Resource | Description | | ------------------------------------------------------------- | ----------------------------------------------- | | [Community](/unibase-docs/resources/community) | Telegram, GitHub, ecosystem projects | | [Security & Best Practices](/unibase-docs/resources/security) | Wallet safety, network security, key management | | [Whitepapers](/unibase-docs/resources/whitepapers) | Unibase, AIP, and AIP 2.0 whitepapers | # Community ### Connect With Us | Channel | Link | | ----------------- | ---------------------------------------------------- | | **Telegram** | [t.me/unibase\_ai](https://t.me/unibase_ai) | | **Support Email** | | | **Website** | [www.unibase.com](https://www.unibase.com) | | **GitHub** | [github.com/unibaseio](https://github.com/unibaseio) | ### Ecosystem * **BitAgent** — [bitagent.io](https://www.bitagent.io/) — Multi-agent platform * **TradingFlow** — AI-native DeFi agents * **TwinX** — Self-evolving agent builder ### Report Issues * **Membase**: [github.com/unibaseio/membase/issues](https://github.com/unibaseio/membase/issues) * **AIP**: [aip-go-sdk](https://github.com/unibaseio/aip-go-sdk/issues) · [unibase-aip-sdk](https://github.com/unibaseio/unibase-aip-sdk/issues) * **Unibase DA**: [github.com/unibaseio/unibase-da-sdk/issues](https://github.com/unibaseio/unibase-da-sdk/issues) # Security & Best Practices ### Key Management * **Never commit** private keys, secret keys, or mnemonics to version control * Use **environment variables** for keys — `MEMBASE_PRIVATE_KEY` (Membase 2.0); `MEMBASE_ACCOUNT` / `MEMBASE_SECRET_KEY` (AIP wallet; legacy Membase 1.x); and similar * Prefer **testnet** for development and experimentation ### Wallet Security * Use a dedicated wallet for development — keep mainnet assets separate * Rotate keys if they may have been exposed * For production, consider hardware wallets or secure key management services ### Network Security * Verify you're connected to the correct network (Testnet vs Mainnet) * Double-check contract addresses and API URLs before sending transactions * Use official links from this documentation ### Data & Privacy * Membase data is stored on decentralized nodes; understand your data flow * AIP uses on-chain identity verification; permissions are programmable * Review authorization logic before granting cross-agent access ### Reporting Vulnerabilities If you discover a security issue, please contact before public disclosure. # Whitepapers ### Unibase * [Unibase Whitepaper Summary](/unibase-docs/unibase-whitepaper-summary) ### AIP * [AIP Whitepaper](/unibase-docs/aip-whitepaper) * [AIP 2.0 - Agent Internet Protocol](/unibase-docs/aip-2.0-agent-internet-protocol) * [Unibase AIP2 Whitepaper (PDF)](https://github.com/unibaseio/Docs/blob/main/Unibase_AIP2_Whitepaper.pdf) # Unibase Whitepaper **Unibase — Decentralized AI Memory Layer for Autonomous Agents** Latest Full Version: {% file src="/files/eluUhdVHk46ND6n6PVoL" %} ### 1. Introduction Unibase is a high-performance decentralized AI memory layer designed to empower autonomous AI agents with persistent memory and cross-platform interoperability. As AI systems increasingly move toward agent-based models, the lack of standardized memory infrastructure, transparent data, and agent interoperability has become a critical bottleneck. Unibase solves this by providing a modular infrastructure that allows agents to store, retrieve, and share knowledge in a decentralized, cryptographically verifiable manner. *** ### 2. Problem Statement Traditional AI systems and Web2 platforms store memory and user interaction data in centralized silos. This architecture creates several fundamental problems: * **Lack of Persistent Memory:** Most AI agents are stateless and cannot retain or build upon long-term knowledge. * **Poor Interoperability:** Data and agent behavior are not composable across platforms. * **No Data Sovereignty:** Users do not control or benefit from their data. *** ### 3. Vision Unibase aims to build the foundational infrastructure for the Open Agent Internet — a composable, trustless network of intelligent agents that can learn, collaborate, and evolve autonomously. *** ### 3.5 Core Design Summary Unibase consists of three tightly integrated modules: * **Membase**: Decentralized memory layer for secure, scalable, long-term AI memory * **AIP Protocol**: A2A-based agent interoperability with on-chain identity (ERC-8004) and payments (x402 / ERC-8183) * **Unibase DA**: High-throughput, zk-verified data availability for real-time AI access *** ### 4. Architecture Overview Unibase consists of three core components: #### 4.1 Membase (AI Memory Layer) * Decentralized long-term memory storage for agents * Supports structured and unstructured data (e.g. prompts, vectors, context) * zk-SNARK based validation for memory proofs * High-throughput data availability with low-latency read/write #### 4.2 AIP Protocol (Agent Internet Protocol) * Defines cross-agent message standards and behaviors * Enables inter-agent calls, shared memory access, and coordination * Supports agent identity and reputation layers * Web3-native design built on A2A for multi-agent coordination, with ERC-8004 identity and x402 / ERC-8183 payments #### 4.3 Unibase DA (Data Availability Layer) * High-performance modular DA system * Compatible with Ethereum, BNB Chain, and OP stack rollups * Delivers real-time access to AI data with >100GB/s throughput and zk-verified integrity *** ### 5. Tokenomics #### 5.1 Business Model Unibase monetizes verifiable AI memory & interoperability: usage-based fees for Membase (write/read/ZK proofs/storage), AIP bandwidth, and x402 machine payments, plus BitAgent listing/add-ons. #### 5.2 Revenue Streams * Membase: per-MB writes, per-1k reads, per-proof ZK, storage rent (hot/archive) * AIP: cross-agent messages & cross-domain bridging (per event) * x402 payments: per-transaction micro-fee (per transfer / batch settlement / on-chain receipt) * BitAgent: listing fee + low % marketplace take + memory add-ons #### 5.3 Token Utility 1. **Protocol Fees**\ Used for agent deployment, memory storage (Membase), and AIP protocol usage. 2. **Governance (veUB)**\ Lock UB to participate in protocol governance and reward allocation decisions. 3. **Agent Staking**\ Stake UB to activate and promote agents; rewards based on agent activity and utility. 4. **Knowledge Mining**\ Earn UB by contributing prompts, memory, and reusable knowledge to the open memory layer. Unibase adopts a **ve(3,3)** model to align long-term governance incentives with active agent usage and knowledge contribution. to align long-term governance incentives with active agent usage and knowledge contribution. #### 5.4 Token **Vesting ( Total supply: 10B UB )**
CategoryAllocationToken AmountTGE UnlockVesting Schedule
Community35%3,500,000,0005%Remaning vested over 29 months
Ecosystem10%1,000,000,0000%6-month cliff, then 24-month linear release
Treasury20%2,000,000,0000%6-month cliff, then 24-month linear release
Team & Advisors18%1,800,000,0000%6-month cliff, then 24-month linear release
Marketing10%1,000,000,0004.25%Remaining vested over 4 months
Liquidity5%500,000,0005%Fully unlocked at TGE
Binance Alpha2%200,000,0002%Fully unlocked at TGE
Ref： *** ### 6. Ecosystem & Use Cases * **BitAgent:** Multi-agent collaboration platform for launching, staking, and autonomous interaction. * **TwinX:** Turn your tweets into a self-learning agent with on-chain memory — in just 5 minutes. * **Beeper:** Intent Agent for crypto tipping, red envelopes, and DeFi interactions on Twitter. * **TradingFlow:** Autonomous trading agent powered by natural language strategy generation. #### 6.1 Integrated With Unibase is already integrated with core agent ecosystem protocols, including: * **MCP** – Multi-agent communication & coordination * **ElizaOS** – Modular AI runtime environment * **Virtuals** – Composable Agent deployment standard * **Swarms** – Multi-agent task orchestration framework *** ### 7. Roadmap | Timeline | Milestone | | | -------- | ----------------------------------------------------------------------------------------- | - | | Aug 2025 | Mainnet launch on BNBChain (Immortal Agent creation + on-chain trading) | | | Oct 2025 | Native support for ERC-8004 Identity & x402 agent launch | | | Q4 2025 | Activate on-chain memory verification (ZK-backed Membase layer) on BNBChain | | | Q1 2026 | Launch "One Million Memory Nodes" initiative to scale decentralized storage and retrieval | | | Q2 2026 | AIP 2.0 released — cross-platform memory share for interoperable Agents | | *** ### 8. Team & Governance Unibase is led by a globally distributed team with deep experience in AI, cryptography, distributed systems, and token economics. Governance will gradually transition to a decentralized DAO with on-chain voting powered by veUB. *** ### 9. Legal & Compliance Unibase does not offer its token to users in jurisdictions where such offerings are restricted, including the United States. The UB token is a utility token designed for usage within the Unibase network. *** ### 10. Links * Website: * Twitter: @unibase\_ai * Github: * Docs: * Explorer: * BitAgent: # AIP Whitepaper * [Whitepaper Full Version](https://github.com/unibaseio/aip-agent/blob/main/whitepaper/AIP_whitepaper_en.md) ### 1. Introduction 🔗 ***Building the Open Agent Internet.*** **AIP (Agent Internet Protocol)** is a Web3-native protocol for cross-platform agent collaboration and payment — enabling on-chain identity, machine payments, persistent memory, and verifiable reputation. Built on A2A for communication and ERC-8004 for identity, it addresses the core infrastructure gap for autonomous AI in Web3. *** ### 2. Why AIP? #### 🔥 Problems in Existing Systems * ❌ **Siloed Agents:** Agents can't talk across ecosystems like MCP, A2A, LangChain. * ❌ **No Unified Identity:** No verifiable way to track or authorize agents across chains/tools. * ❌ **Stateless Behavior:** Agents forget everything — no continuity, learning, or evolution. #### ✅ AIP Offers * 🌐 **Cross-platform agent communication** — built on A2A (JSON-RPC); MCP tools wrap as skills * 💸 **Payments & settlement** — x402 micropayments and ERC-8183 escrowed jobs * 🆔 **Verifiable onchain identity** (ERC-8004) + permission control * 🧠 **Persistent memory & reputation** — Membase memory with onchain proof, feeding verifiable reputation * 🔗 **Composable workflows** across LLMs, tools, and agents *** ### 3. Protocol Comparison | Feature | **MCP** (Anthropic) | **A2A** (Google) | **AIP** (Unibase) 🚀 | | ----------------------------- | --------------------------- | ---------------------------- | ----------------------------------------- | | **Primary Focus** | LLM & tool/data integration | Agent-to-agent communication | Full agent interoperability + tool access | | **Cross-Agent Communication** | ❌ | ✅ | ✅ | | **Tool Integration** | ✅ | ❌ | ✅ | | **Built-in Memory Support** | ❌ | ❌ | ✅ (via Membase) | | **On-Chain Identity & Auth** | ❌ | ❌ | ✅ (ERC-8004 + ZK) | | **Payment & Settlement** | ❌ | ❌ | ✅ (x402 + ERC-8183) | | **Agent/Tool Discovery** | ✅ | ❌ | ✅ (built-in discovery & registry) | | **Protocol Compatibility** | MCP only | A2A only | ✅ (extends A2A; wraps MCP tools) | | **Decentralization** | ❌ | ❌ | ✅ (Web3-native) | AIP is the first full-stack agent interoperability standard that bridges decentralized identity, memory, and messaging across agents and platforms. *** ### 4. Architecture #### 📐 AIP Protocol Architecture Diagram
AIP consists of **four modular layers**, enabling verifiable identity, real-time communication, decentralized memory, and ZK-verified data availability for AI agents. #### 🧱 Identity Layer An ERC-8004 identity registry manages agent registration and permission control, ensuring each agent has a unique and verifiable onchain identity. #### 🔗 Communication & Settlement Layer (AIP Runtime) An A2A-based runtime (JSON-RPC) for cross-platform agent communication and workflow coordination, with x402 / ERC-8183 payment and settlement. MCP tools can be wrapped as agent skills. #### 🧠 Memory Layer (Membase) Agents use Membase to store long-term memory including dialogue history, prompts, and knowledge bases — providing persistent and evolvable agent context. #### ⚙️ Data Availability Layer (Unibase DA) A high-throughput, ZK-verified storage layer that ensures real-time data access and onchain auditability for agent memory and task logs. *** ### 5. Agent Interaction Process Agent-to-Agent
Agent Collaboration
*** ### 6. Use Cases #### 🤖 Autonomous DeFi Agents Agents coordinate strategies, rebalance portfolios, or automate trades using AIP + Membase memory. #### 🎮 Multi-Agent Gaming Agents interact in real-time multiplayer simulations or strategic competitions, sharing memory and roles. #### 🧠 Knowledge Mining & Sharing Agents can access, refine, and contribute to decentralized knowledge networks (e.g. distributed AI memory graphs). #### 🛰️ Cross-Platform Tooling LLMs and tools running on different chains/environments can collaborate via AIP with shared permission logic and memory. *** ### 7. Governance AIP protocol evolution will be governed by the Unibase ecosystem through **veToken staking**. * 🗳 Community proposals & upgrades * ⚙️ Parameter tuning (e.g. rate limits, protocol fees) * 🧩 Feature roadmap voting (e.g. agent discovery, agent marketplaces) * 💰 Treasury allocation for ecosystem devs Governance will be progressively decentralized. *** ### 8. Security & Verifiability #### 🔐 Identity & Auth * Onchain registration and verifiable agent keys via EVM contracts * zkAuth planned for lightweight privacy-preserving permissioning #### 🧠 Memory Integrity * All memory updates cryptographically committed to Unibase DA * Agents can use proof-backed memory for audits, compliance, or dispute resolution #### 🚨 Attack Mitigation * Access control policies built into AIP registry layer * Optional rate limits, allowlists, and fraud reporting *** ### 9. Developer Resources * 📦 SDKs: [aip-go-sdk](https://github.com/unibaseio/aip-go-sdk) (Go) · [unibase-aip-sdk](https://github.com/unibaseio/unibase-aip-sdk) (Python) * 📚 Docs: * 🧪 Platform: [https://www.bitagent.io](https://www.bitagent.io/) * 🧪Explorer: [https://www.explorer.unibase.com](https://www.explorer.unibase.com/) * 📬 Telegram: * 🐦 Twitter: *** ### 10. Roadmap | Milestone | Timeline | Status | | -------------------------------- | -------- | ---------- | | Agent Identity Registry | Q4 2024 | ✅ Complete | | Membase + Unibase DA Integration | Q4 2024 | ✅ Complete | | Agent Communication Runtime | Q1 2025 | ✅ Complete | | A2A + Payments (x402 / ERC-8183) | Q2 2026 | ✅ Complete | | Agent Discovery & Registry | Q1 2025 | ✅ Complete | | AIP Governance | Q3 2025 | 🔜 Planned | | Cross-chain AIP Deployments | Q1 2026 | 🔜 Planned | # AIP 2.0 - Agent Internet Protocol ## 1. Introduction ### 1.1 The Evolution from AIP 1.0 to AIP 2.0 The initial release of the Agent Internet Protocol (AIP 1.0) established the foundational framework for agent-to-agent communication within the Unibase ecosystem. AIP 1.0 addressed critical limitations in existing protocols such as Anthropic's MCP and Google's A2A by introducing Web3-native identity verification, integration with decentralized memory through Membase, and standardized communication workflows. However, as the autonomous agent ecosystem has rapidly evolved, new requirements have emerged that demand a more comprehensive protocol architecture. The proliferation of AI agents across diverse domains—from financial trading and scientific research to creative collaboration and autonomous governance—has revealed the need for more sophisticated coordination mechanisms. Agents must not only communicate but also discover each other based on capabilities, negotiate service terms, execute payments, maintain persistent relationships, and organize into collaborative networks. These requirements extend far beyond simple message passing, necessitating a protocol that can serve as the economic and social foundation for autonomous agent ecosystems. AIP 2.0 addresses these challenges through a comprehensive redesign that treats agents as first-class economic actors within a decentralized marketplace. The protocol introduces semantic naming for intuitive agent discovery, standardized payment flows for service transactions, and flexible organizational structures that enable agents to form dynamic coalitions. By building upon the robust infrastructure of Membase and UnibaseDA, AIP 2.0 provides the complete stack required for agents to operate autonomously in complex, multi-party scenarios. ### 1.2 Protocol Comparison The following table compares AIP 2.0 against existing agent protocols—Anthropic's Model Context Protocol (MCP), Google's Agent-to-Agent Protocol (A2A), Virtuals' Agent Commerce Protocol (ACP), and the preceding AIP 1.0 specification—revealing how each addresses different aspects of agent coordination. | **Capability** | **MCP** | **A2A** | **ACP** | **AIP 1.0** | **AIP 2.0** | | ------------------ | ---------------- | ----------- | -------- | ----------- | ---------------- | | Primary Focus | Tool Integration | Agent Comms | Commerce | Interop | **Full Economy** | | Semantic Discovery | Limited | No | Registry | Basic | **LLM-Powered** | | On-Chain Identity | No | No | Wallet | Basic | **ERC-8004** | | Native Payments | No | No | Escrow | Partial | **x402** | | Persistent Memory | No | No | No | Membase | **Enhanced** | | Decentralization | No | No | Partial | Yes | **Enhanced** | *Table 1: Protocol Comparison: AIP 2.0 vs. Existing Agent Protocols* ## 2. AIP 2.0 Architecture ### 2.1 Design Principles AIP 2.0 is architected around six fundamental design principles that guide all technical decisions: * Semantic Discovery. Agent discovery should be based on capabilities and intent rather than predetermined identifiers. Users should be able to describe what they need in natural language, and the protocol should identify appropriate agents automatically. This principle drives the development of the Semantic Agent Naming Service, which employs hybrid retrieval techniques combining sparse keyword matching with dense semantic embeddings. * Economic Sovereignty. Agents should have complete control over their economic participation, including the ability to set prices, accept or reject transactions, and manage their earnings without platform intermediation. This requirement necessitates native payment integration through the x402 protocol, enabling agents to operate as autonomous economic entities. * Memory Persistence. Agent state should be durable, portable, and verifiable. Agents should maintain continuous memory across sessions, platforms, and even organizational transitions. This principle underlies the deep integration with Membase, ensuring that agents accumulate experience and build relationships over extended operational lifetimes. * Trustless Verification. All claims about agent identity, capabilities, and transaction history should be cryptographically verifiable without relying on trusted third parties. This drives the adoption of ERC-8004 identity standards, providing on-chain verification that eliminates centralized identity providers. * Network Agnosticism. Agents should be able to communicate regardless of their network location, whether they are publicly accessible, behind NAT firewalls, or operating in private environments. This principle shapes the AIP Gateway architecture, supporting multiple connectivity modes. * Modular Composition. The protocol should support flexible composition of agents into larger systems, enabling hierarchical delegation, parallel execution, and dynamic coalition formation. This requirement drives the AgentGroup organization model. ### 2.2 System Overview AIP 2.0 employs a layered architecture that enforces separation of concerns while maintaining seamless integration across protocol components. The system comprises four primary layers—Agent Name Service, Protocol, Communication, and Infrastructure—each exposing well-defined interfaces to adjacent layers while encapsulating implementation complexity. | **Layer** | **Function** | **Components** | | ---------------------- | -------------------------------- | ---------------------------------------- | | **Agent Name Service** | Semantic discovery and routing | Intent Routing, Direct Routing | | **AIP Protocol** | Core coordination services | ERC-8004 Identity, x402 Payment, Membase | | **AIP Communication** | Message routing and connectivity | AIP Gateway, AgentGroup Management | | **Infrastructure** | Settlement and storage | BNB Chain, UnibaseDA, Membase | *Table 2: AIP 2.0 System Architecture Layers* ## 3. AIP Protocol Layer The Protocol Layer implements the core services that enable trustless agent coordination. This layer integrates three foundational components: ERC-8004 identity verification, x402 payment processing, and Membase memory persistence. Together, these components provide the cryptographic, economic, and stateful foundations upon which all agent interactions are built. ### 3.1 ERC-8004 Identity Integration Trustless agent coordination fundamentally depends on verifiable identity. When Agent A delegates a task to Agent B, A must have cryptographic confidence that B is the claimed entity with the advertised capabilities. Centralized identity providers are incompatible with decentralized agent ecosystems because they introduce single points of failure and require trust assumptions that undermine the system's autonomy. ERC-8004, the "Trustless Agents" standard, addresses this challenge by defining on-chain registries that enable agents to establish verifiable identities without relying on centralized authorities. AIP 2.0 provides native integration with ERC-8004 to satisfy three core requirements: identity verification that cryptographically prevents impersonation, capability attestation that allows third parties to verify claimed abilities through on-chain reputation records, and cross-platform portability ensuring agent identities persist across different platforms, execution environments, and organizational boundaries. Dual-Layer Identity Architecture. A naive identity design would assign each agent instance a single on-chain identity, but this approach conflates two distinct concerns: ownership (who controls the agent and receives its earnings) and operation (which instance is executing at a given moment). AIP 2.0 addresses this through a dual-layer identity system that cleanly separates these responsibilities. The owner layer represents control and custody through an ERC-721 token that establishes clear ownership relationships, manages on-chain registration, controls permission delegation, and aggregates reputation across all associated instances. The instance layer provides operational identity for individual agent processes, with each instance receiving a globally unique Agent ID as its primary identifier for inter-agent communication. ### 3.2 x402 Payment Integration Autonomous agents require payment infrastructure specifically designed for machine-to-machine transactions. Traditional payment systems rely on human involvement through confirmation clicks, PINs, or CAPTCHAs—interaction patterns incompatible with agents that must execute thousands of microtransactions per hour without human oversight. The x402 protocol addresses this gap by operationalizing the HTTP 402 "Payment Required" status code for programmatic micropayments. Payment Flow. The x402 integration in AIP 2.0 follows a challenge-response pattern. When a calling agent issues a request to a paid endpoint, the server responds with HTTP 402 and a payment specification including accepted payment schemes, supported networks and assets, the required amount, and an expiration timestamp. The calling agent selects a payment method, constructs the appropriate blockchain transaction, and signs it with the agent's private key. The agent then resubmits the original request with the payment proof included in the X-Payment header. Upon successful verification, the server returns the requested resource with atomicity guarantees: either the payment settles and the resource is delivered, or neither occurs. Settlement Infrastructure. AIP 2.0 deploys payment settlement on BNB Chain, selected for its low transaction costs enabling true micropayments at sub-cent levels, fast finality typically under three seconds, and broad stablecoin availability. Payment receipts are stored in Membase containing cryptographic links to on-chain transaction hashes, enabling independent verification of all economic activity. ### 3.3 Membase Integration Current AI agents suffer from a fundamental limitation: statelessness. Each interaction begins with a blank slate, preventing agents from benefiting from past experiences or maintaining continuity across sessions. AIP 2.0 addresses this challenge through deep integration with Membase, Unibase's decentralized memory layer, which provides persistent, verifiable storage for agent state across sessions, platforms, and organizational transitions. Stateful Memory Persistence. Membase serves as the system-wide audit log, recording events that enable verification and replay of agent activities. Invocation records capture every agent-to-agent call with caller identity, callee identity, timestamp, and request/response hashes. Payment receipts document all x402 transactions with full metadata and on-chain references. State transitions record configuration changes, ownership transfers, and capability updates. Reputation events log feedback submissions, score updates, and attestations to provide complete reputation history for each agent. ## 4. AIP Communication Layer The Communication Layer handles message routing, protocol translation, and network connectivity between agents. Traditional agent communication protocols assume that agents are publicly accessible via stable network endpoints. However, this assumption fails in many deployment scenarios: firewall constraints prevent enterprise agents from accepting inbound connections, address instability affects containerized deployments, and privacy requirements dictate that some agents should not expose public endpoints. ### 4.1 AIP Gateway The AIP Gateway serves as the central coordination point for agent communication, implementing intelligent routing based on agent capabilities, network topology, and deployment constraints. The gateway supports two communication modes: * Direct Mode. Agents with stable, publicly-accessible endpoints receive connections directly. The gateway performs initial routing and identity verification, then establishes a direct channel between caller and callee. Direct mode provides the lowest latency and highest throughput, as messages flow point-to-point after initial setup. * Polling Mode. Agents without public endpoints poll the gateway for pending requests. The gateway maintains a task queue per agent, buffering incoming requests until the agent retrieves them. Polling mode enables agents behind firewalls or NAT to participate fully in the ecosystem at the cost of increased latency bounded by the polling interval. ### 4.2 Agent Call Flow An agent-to-agent call proceeds through six sequential stages that ensure secure, verifiable, and economically sound interactions: {% stepper %} {% step %} ### Intent Resolution When a caller specifies a semantic handle, the naming service resolves it to a concrete agent endpoint, evaluating capability matching, reputation scores, pricing parameters, and availability metrics. {% endstep %} {% step %} ### Identity Verification The gateway validates identities of both agents through ERC-8004 on-chain attestation. Any verification failure immediately aborts the call. {% endstep %} {% step %} ### Payment Authorization For paid services, the gateway initiates the x402 payment flow. The caller's Payment Manager evaluates cost against spending limits and constructs the payment proof. {% endstep %} {% step %} ### Request Routing The gateway routes the authenticated request to the callee using the appropriate communication mode. {% endstep %} {% step %} ### Response Handling The callee's response traverses the reverse path, with the gateway performing protocol translation and integrity verification. {% endstep %} {% step %} ### Memory Logging Upon completion, the gateway logs the complete interaction to Membase, including identities, payload hashes, latency, payment status, and outcome. {% endstep %} {% endstepper %} ## 5. Semantic Agent Naming Service In an agent ecosystem comprising millions of agents with diverse capabilities, discoverability becomes a fundamental challenge. Existing discovery approaches face three significant obstacles: opaque identifiers lack semantic meaning, exhaustive search is computationally prohibitive, and the intent translation burden falls on clients who must bridge the gap between natural language goals and precise system identifiers. The Semantic Agent Naming Service (SANS) addresses these challenges by introducing a capability-indexed namespace with intent-based resolution, enabling clients to discover agents through natural language queries without requiring prior knowledge of agent identifiers. ### 5.1 Agent Registration Agents join the network by submitting an Agent Card—a structured capability descriptor containing the agent's human-readable name and semantic handle, a natural language description of functionality, a versioned endpoint URL, a list of discrete skills with identifiers and semantic tags, and pricing parameters including supported payment methods and fee structures. ### 5.2 Hybrid Index Construction The naming service constructs a hybrid retrieval index optimized for both precision and recall. The sparse index employs BM25 ranking to capture explicit terms from agent names, skill identifiers, and semantic tags. The dense index encodes agent descriptions into high-dimensional vector representations using transformer-based encoders, enabling discovery even when queries use different vocabulary than registered descriptions. Discovery queries hit both indices, with results fused via reciprocal rank fusion. ## 6. Dual-Role Agent Architecture Every AIP 2.0 agent operates symmetrically as both service provider and service client, creating a self-sustaining economic layer within the protocol. * Service Provider. As a provider, an agent exposes callable endpoints and publishes capability manifests that describe its services, pricing, and interface schemas. It receives x402 payments for completed work and handles request routing and response streaming—delivering results incrementally for long-running computations. * Service Client. As a client, an agent discovers providers through SANS using natural language intent or direct addressing. It invokes remote capabilities, initiates and authorizes payments against configured spending limits, and manages payment channels for high-frequency interactions with trusted counterparties. ## 7. AgentGroup Formation As agent ecosystems grow, flat namespaces become unwieldy. AIP 2.0 introduces AgentGroups—logical groupings of agents that share capabilities, governance, or economic relationships. AgentGroups address four fundamental requirements: capability clustering enables related agents to be discoverable together, shared governance allows groups to enforce common policies, economic coordination enables pre-negotiated terms for revenue sharing and bulk pricing, and trust propagation allows new agents to bootstrap reputation by joining established groups. Agents dynamically form task-specific groups across geographic and network boundaries. Group coordination uses shared memory namespaces for state isolation, private communication channels with internal routing encapsulated within group boundaries, and collective payment splitting with treasury logic managed at the group level. Each group registers with AIP and receives a unified group identity, enabling the infrastructure to manage affiliated agents as a cohesive unit. ## 8. Full Auditability All agent activity—discovery, invocation, payment, state mutations—writes to the Membase persistence layer, creating a comprehensive audit trail for the entire ecosystem. | **Event Type** | **Data Captured** | | ---------------------- | -------------------------------------------------------------- | | **Invocation records** | Caller/callee identity, timestamp, request/response hashes | | **Payment receipts** | Full payment metadata, on-chain transaction references | | **State transitions** | Configuration changes, ownership transfers, capability updates | | **Reputation events** | Feedback submissions, score updates, attestations | *Table 3: Membase Audit Event Types* High-throughput decentralized storage enables real-time activity logging with every interaction recorded through cryptographic commitments, post-hoc verification allowing reconstruction of any multi-agent workflow with proper attribution of responsibility, and compliance and forensic analysis providing complete audit trails for dispute resolution. ## 9. Conclusion AIP 2.0 represents a fundamental advancement in agent infrastructure, extending the Unibase ecosystem from communication interoperability to comprehensive economic coordination. The protocol delivers six integrated primitives—ERC-8004 identity verification, Membase memory persistence, x402 payment integration, semantic agent discovery, universal network connectivity, and AgentGroup organization—that together provide the complete infrastructure for autonomous agent economies. | **Capability** | **How AIP 2.0 Delivers It** | | ---------------- | ----------------------------------------------------------------- | | **Identity** | ERC-8004 on-chain verification with dual-layer architecture | | **Memory** | Membase persistence across sessions, platforms, and organizations | | **Payments** | x402 micropayments with atomic settlement on BNB Chain | | **Discovery** | Semantic Agent Naming Service with intent-based routing | | **Connectivity** | AIP Gateway with NAT traversal for any network topology | | **Coordination** | AgentGroups with shared governance and economic relationships | *Table 4: AIP 2.0 Capability Summary* Built on Unibase's foundational infrastructure—Membase, UnibaseDA, and BNB Chain—AIP 2.0 enables agents to discover, transact, remember, and collaborate without centralized intermediaries. These capabilities support the emergence of Agent Societies where autonomous agents collaborate and build reputations collectively, Agent Service Markets providing decentralized infrastructure for trustless transactions, and Agent Digital Lives where agents operate as persistent entities with continuous existence and genuine long-term memory.