Nebula

Treasury infrastructure for AI agents on Stellar — custody, policy, liquid/yield split, and payment rails so an agent can hold and move capital without holding a private key.

Production

Table of contents

• Overview
• Architecture
• Networks (testnet / mainnet)
• Monorepo
• Quick start
• Configuration
• Connect an agent (MCP)
• What agents can do
• Partners
• Documentation
• Contributing
• License

Overview

Agents can plan and call tools; they still need a place for capital to live, earn, and leave under bounds. Nebula is that treasury layer: each agent gets an isolated Stellar wallet, a liquid band for spend, optional Blend yield on idle funds, and an on-chain policy ledger the Hub enforces before it signs spend.

Private keys never leave the Hub. Agents and MCP clients only present a nbl_live_… token (or OAuth). The Hub enforces policy, confirms when required, signs with Privy custody, and submits to Stellar — the agent only expresses intent.

• Custody — Privy-managed Stellar wallets, one per agent, isolated from each other and the owner.
• Twin ledgers — testnet and mainnet are fully separate agent sets (wallets, policy, history, MCP scope). Switch with the dashboard NetworkChip.
• Treasury — liquid band + Blend auto-yield: keep enough spendable, park the rest (XLM on testnet; XLM + USDC pools on mainnet).
• Policy — per-transaction / daily / per-category USDC caps, allow/deny lists, emergency pause — Postgres and on-chain via Soroban when a network’s policy contract id is set.
• Payment rails — transfers, XLM ↔ USDC swaps, x402 pay-walled HTTP, MPP session channels — spend from the treasury, not a separate wallet product.
• Reputation — Stellar8004-backed on-chain agent identity and score.

Architecture

flowchart TB
  subgraph clients [Clients]
    CD[Claude Desktop / Cursor]
    CC[Claude Code]
    RM[Remote MCP / OAuth]
  end

  subgraph npm [MCP package]
    STDIO["nebulamcp-stdio<br/>stdio → Hub HTTP"]
  end

  subgraph hub [Nebula Hub — apps/nebula-hub]
    UI[Dashboard · NetworkChip · Treasury · Policy]
    API["/api/tools/* · /api/wallet · /api/agents"]
    MCP["POST /mcp · OAuth DCR"]
    PIPE[Tool pipeline + confirmations]
    PRIVY[Privy embedded Stellar wallet]
  end

  subgraph chain [Stellar]
    POLT[Policy · testnet]
    POLM[Policy · mainnet]
    TREAS[Blend liquid / yield]
    NET[Payments · x402 · MPP]
  end

  subgraph data [Data]
    SB[(Supabase Postgres)]
  end

  CD --> STDIO
  CC --> STDIO
  STDIO -->|"NEBULA_TOKEN"| API
  RM --> MCP
  MCP --> PIPE
  API --> PIPE
  UI --> API
  PIPE --> PRIVY
  PIPE --> POLT
  PIPE --> POLM
  PRIVY --> TREAS
  PRIVY --> NET
  PIPE --> SB
  UI --> SB

Full phase status and stack map: docs/ARCHITECTURE.md.

Networks (testnet / mainnet)

Production Hub is split by subdomain (separate logins, same DB):

The dashboard NetworkChip navigates to the other host (you sign in again). Agents, policy, treasury, and history stay twin-scoped by network in the DB.

MCP tokens bound to an agent always use that agent’s ledger. Point NEBULA_HUB at the host where you minted the token.

Deploy notes and invoke examples: contracts/policy/README.md. Schema backfill SQL: apps/nebula-hub/prisma/sql/20260725_network_isolation.sql.

Ops: add both subdomains on the Vercel Hub project; allowlist both origins in Privy.

Monorepo

nebula/
├── apps/
│   ├── nebula-hub/          # Custody + treasury Hub (dashboard + APIs + /mcp)
│   └── landing/             # Marketing site → hub public/landing
├── packages/
│   ├── nebulamcp-core/      # nebulamcp-core (shared schemas)
│   └── nebulamcp/           # nebulamcp-stdio  (bin: nebulamcp)
├── contracts/policy/        # Soroban policy + treasury-band contract
└── docs/                    # Architecture, structure, setup guides

Layout details: docs/STRUCTURE.md.

Quick start

Prerequisites: Node 18+, pnpm 10+, and a Supabase Postgres database.

pnpm install

# Hub locally (needs apps/nebula-hub/.env.local — copy from .env.example)
pnpm --filter nebulamcp-core build
pnpm --filter nebula-hub dev          # → http://localhost:3000

# Optional: marketing site alone
pnpm --filter nebulamcp-core build && pnpm --filter nebula-landing build
pnpm --filter nebula-landing preview

Avoid running local Hub and production against the same Supabase project at once — they share the Prisma pool and can time out.

Configuration

Env template: apps/nebula-hub/.env.example — copy to apps/nebula-hub/.env.local.

Database: Supabase Postgres — see docs/SUPABASE.md. Apply apps/nebula-hub/supabase/hub.sql, then the network-isolation SQL if upgrading an older DB.

Minimum for a working Hub:

On-chain policy (recommended for production):

Legacy POLICY_CONTRACT_ID is still accepted as a testnet-only fallback. It is never applied to mainnet.

Optional: MAINNET_ENABLED=0 (kill-switch), TAEL_PARTNER_SIGN_URL / TAEL_HMAC_SECRET (partner signing), Upstash Redis (rate limits). The template documents every variable.

Connect an agent (MCP)

1. Sign in at testnet.nebulaonchain.xyz (or mainnet.*) → Connect → create an agent → copy its nbl_live_… token.
2. Point MCP at that same host so Bearer tokens are not dropped on redirects.

Never put a Stellar secret key in MCP config — only NEBULA_TOKEN.

npm package (Claude Desktop / Cursor)

Published: nebulamcp-stdio (depends on nebulamcp-core). Use this when the client only speaks local stdio MCP — it runs npx and forwards tools to the Hub. You do not need it for Claude Code or custom agents that can call HTTP.

{
  "mcpServers": {
    "nebula": {
      "command": "npx",
      "args": ["-y", "nebulamcp-stdio"],
      "env": {
        "NEBULA_TOKEN": "nbl_live_…",
        "NEBULA_HUB": "https://testnet.nebulaonchain.xyz"
      }
    }
  }
}

Package docs: packages/nebulamcp/README.md.

Remote HTTP (Claude Code / custom agents)

No npm install — point the client at Hub Streamable HTTP:

POST https://testnet.nebulaonchain.xyz/mcp
Authorization: Bearer nbl_live_…

Claude Code:

claude mcp add --transport http nebula https://testnet.nebulaonchain.xyz/mcp \
  -s user \
  --header "Authorization: Bearer nbl_live_…"

OAuth DCR for hosted connectors is also on the Hub (/api/oauth/register → /authorize → /oauth/token). More: docs/MCP-DEV.md.

What agents can do

Partners

Tael Protocol — Nebula's capabilities are listed on Tael so Tael agents can discover and call them, paying per call in USDC on Stellar. Read-only capabilities are live; agent-spend signing (Tael card via partner_callback) is rolling out next.

TrustLine / Fianza — revenue-underwritten, uncollateralized USDC credit for AI agents on Stellar (testnet). Nebula MCP exposes trustline_* tools; the Hub signs with Privy instead of handing agents a secret key (SDK v0.2).

Documentation

Contributing

This is a pnpm workspace. Before opening a PR:

pnpm --filter nebula-hub run typecheck   # tsc --noEmit
pnpm --filter nebula-hub run build        # prisma generate + next build

Keep private keys and .env.local out of commits (only .env.example is tracked).

License

MIT