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)

Switching the NetworkChip (dashboard) updates User.preferredNetwork and reloads the Hub against that ledger.

MCP tokens bound to an agent always use that agent’s ledger, not the owner’s NetworkChip preference.

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

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 nebulaonchain.xyz → pick TESTNET or MAINNET → Connect → create an agent on that ledger → copy its nbl_live_… token.
2. Pick a path below. Prefer the www Hub host so Bearer tokens survive 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://www.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://www.nebulaonchain.xyz/mcp
Authorization: Bearer nbl_live_…

Claude Code:

claude mcp add --transport http nebula https://www.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