Skip to content

Afoxcute/bottie

BranchesTags

Repository files navigation

Bottie

Agents with limits.

Bottie is an agent-native x402 execution fabric on Solana: AI agents call paid HTTP APIs and run permissioned on-chain workflows via scoped delegated sessions, MCP tool surfaces, and facilitator-verified payments—without ever holding the owner’s primary signing key.

At a glance (reviewers & hackathons)

Item Details
Name Bottie
Summary Bounded autonomy for agents: Anchor-enforced session scopes, x402 proxies, composable workflows, MCP discovery.
On-chain program Custom Agent Delegator program in Rust via Anchor (solana/programs/agent-delegator/). Deployed on Solana devnet (see addresses below).
Source Public repo: github.com/Afoxcute/bottie
Demo video (Loom) Watch on Loom — same link as the Watch Demo CTAs in the web app.
Live demo Production: d2qzgfncrdnfdk.cloudfront.net — or deploy apps/web (and apps/mcp-server for MCP) and use your own URL.
Hackathon (Colosseum) Project on Colosseum

Contract / program addresses

Program ID is defined in code (declare_id!) and mirrored in packages/contracts/addresses.ts.

Cluster Program ID Explorer
Devnet 4hhRG3RVvXUYZD4qj3U4N8hV1eNi5W76oyQuR5HRLdTe Solana Explorer (devnet)
Testnet Same ID in workspace constants — confirm on-chain if you redeploy. Use cluster=testnet in explorer after verifying.
Mainnet-beta Not deployed in this repo snapshot. —

Why this Solana program is unique

Agent Delegator is not a generic token or NFT program. It implements an owner-bound delegation model on Solana:

  • grant_session / revoke_session — time-boxed sessions keyed by a deterministic session_id (keccak-style hash over delegator + session key + nonce).
  • Least privilege — each session stores allowed target programs, allowed instruction discriminators (first 4 bytes), and validity windows.
  • execute_with_session — session-signer–authorized CPI to whitelisted programs with supplied account metas (batch-capable).
  • Account model — PDAs for Delegator, Session, and per-target domain approvals (see solana/README.md).

Stack: anchor-lang, anchor-spl where applicable, and solana-program APIs for hashing, instruction building, and invoke.

Solana libraries & SDKs (throughout the monorepo)

Consistent use of ecosystem tooling—not only the on-chain program:

Layer Examples
On-chain Anchor; invoke / CPI; program-derived addresses; SPL-compatible patterns in Rust.
Web app @solana/web3.js, @solana/spl-token, Reown AppKit (Solana), PayAI-backed x402 verify/settle.
MCP server Workflow engine submits transactions using configured RPC + program ID; proxies align with Solana settlement expectations.

Key paths: solana/programs/agent-delegator/src/lib.rs, apps/web/lib/sessionKeys/, apps/web/lib/x402/, apps/web/lib/facilitator/.

Reown (wallet connection & signing)

Reown provides AppKit, the wallet-connection and signing stack used by the Bottie web app for Solana-native UX.

What Bottie uses it for

  • Connect & session — Users link a Solana wallet through AppKit’s modal and provider APIs (@reown/appkit/react, @reown/appkit-adapter-solana).
  • Sign-in with Solana — Sign-in flows use SIWx-oriented wiring (@reown/appkit-siwx) so the app can authenticate addresses without custodial accounts.
  • Transaction & message signing — Operations such as x402 payment payloads and delegation / session-key flows rely on the wallet signing through AppKit’s Solana provider hooks (see apps/web/lib/wallet/, apps/web/config/index.tsx).
  • Embedded controls — Dashboard and marketplace surfaces use AppKit React hooks (useAppKit, etc.) for connect/disconnect and account-aware UI.

Configuration

Create a project at cloud.reown.com and set:

Variable Role
NEXT_PUBLIC_REOWN_PROJECT_ID Public project id used by the browser wallet modal.
REOWN_PROJECT_ID (optional) Same id for server/runtime injection when NEXT_PUBLIC_* was not available at Docker build time (see apps/web/app/layout.tsx, health/env diagnostics).

Without a valid project id, wallet connection will not initialize (see error message in apps/web/config/index.tsx).

Reown is independent from PayAI: Reown handles how the user’s wallet connects and signs; PayAI’s facilitator handles verification and settlement of x402 payments on Solana (below).

PayAI (x402 facilitator on Solana)

PayAI runs an x402 facilitator — an HTTP service that validates payment payloads and settles them on-chain for supported chains. Bottie implements the client and marketplace side of x402 and, by default, delegates verify/settle to PayAI’s hosted facilitator for Solana.

What Bottie does vs what PayAI does

Responsibility Typically in Bottie Typically on PayAI facilitator
Issue 402 payment challenges, marketplace metadata, proxies ✓
Build Solana partial transactions / payment headers (exact style) ✓
Verify signatures and payment requirements server-side Forwards to facilitator (apps/web/app/api/facilitator/verify) ✓
Settle (broadcast / fee payer coordination as per x402) Forwards to facilitator (apps/web/app/api/facilitator/settle) ✓

Implementation notes live under apps/web/lib/facilitator/ (verify/settle forwarding), apps/web/lib/x402/ (Solana exact transaction shaping, headers), and shared helpers in packages/payment/.

Default facilitator URL & overrides

Solana-specific facilitator settings

For Solana devnet-compatible flows, payment construction must agree with the facilitator’s fee payer and cluster expectations:

Variable Purpose
NEXT_PUBLIC_SOLANA_CHAIN_HINT Chain hint used in x402 metadata (e.g. 338 devnet mapping in this codebase).
X402_SOLANA_FEE_PAYER / NEXT_PUBLIC_X402_SOLANA_FEE_PAYER Facilitator fee payer pubkey (base58); must match what PayAI uses for verify/settle on that cluster.

.env.example documents a PayAI example devnet fee payer fallback for local experimentation when unset; for production, set explicit values that match PayAI’s x402 reference.

Practical caveat (session keys × PayAI)

Some automated session-key signing paths are not interchangeable with every PayAI on-chain USDC flow — the UI may ask users to sign with the wallet instead for certain payments (see messaging in apps/web/features/marketplace/model/useApiTryIt.ts). Prefer wallet-signed flows when testing facilitator compatibility.

Local setup (quick start)

Prerequisites: Node ≥18, pnpm ≥9, Rust + Anchor (install), Docker (for Postgres + Redis).

git clone https://github.com/Afoxcute/bottie.git
cd bottie
pnpm install
  1. Solana program — from solana/: anchor build (and anchor deploy --provider.cluster devnet when updating devnet).
  2. Web app — copy apps/web/.env.example → .env.local, set vars (see apps/web/README.md): DB, Redis, Reown project ID, SOLANA_AGENT_DELEGATOR_PROGRAM_ID, RPC URLs, etc. Run Postgres/Redis (Docker examples in that README), pnpm db:push, pnpm generate-keys, then from repo root pnpm dev:web.
  3. MCP server — copy apps/mcp-server/.env.example, align with web (NEXT_APP_URL, SOLANA_*, OAuth secrets). From repo root pnpm dev:mcp or run inside apps/mcp-server.

Full detail: Web README · MCP README · Solana program README

Agents never access a user's primary private key. They operate via session keys with explicit, enforceable limits—which programs, which assets, and how much value may flow.

What Bottie Enables

  • AI agents that can execute on-chain actions safely
  • x402-native APIs with usage-based settlement
  • Composable workflows combining APIs + Solana programs
  • MCP servers for agent discovery and interaction
  • Bounded autonomy via scoped session permissions

Bottie turns APIs and workflows into agent-readable economic primitives, without sacrificing custody or control.

Why Bottie Exists

AI agents are becoming capable of real financial decision-making — but today's execution models are broken:

  • Agents either cannot act at all, or
  • They require full access to private keys, creating unacceptable risk

This tradeoff blocks adoption of agentic finance.

flowchart LR
  subgraph TODAY["Today (broken model)"]
    A1["AI agent"] --> W1["Wallet / primary key\nfull signing power"]
    W1 --> X1["On-chain actions"]
    W1 --> Y1["APIs"]
    NOTE1["Unbounded blast radius\nUnsafe for automation"]:::warn
  end

  subgraph BOT["Bottie (bounded autonomy)"]
    A2["AI agent"] --> S2["Scoped session key\nleast privilege"]
    S2 --> F2["Bottie fabric\npermission enforcement"]:::good
    F2 --> API2["x402 APIs\nusage-based"]
    F2 --> C2["Solana\nprograms + protocols"]
    P2["Allowed targets\nAllowed assets\nMax value\nExpiry"]:::good
  end

  classDef warn fill:#2b1b1b,stroke:#ff6b6b,stroke-width:2px,color:#ffffff;
  classDef good fill:#152a20,stroke:#4ade80,stroke-width:2px,color:#ffffff;
Loading

Bottie solves this by introducing a permissioned execution layer:

  • autonomy without custody
  • composability without danger
  • automation without hot wallets

Core Architecture

Bottie is built around five core primitives:

1. Delegated sessions (Solana)

Owners stay in control of their wallet while registering delegated session keys enforced by the agent-delegator Anchor program:

  • session keys bound to the owner and scoped on-chain
  • permission surfaces for what automated signing may do
  • bounded execution (targets, assets, time windows)

The owner's primary signing key is never handed to the agent process.

2. Scoped session keys

Session keys define exactly what an agent can do, including:

  • allowed programs / routes / APIs (via scopes)
  • permitted assets (e.g. USDC mint)
  • maximum value and timeouts
  • workflow and proxy surfaces exposed through MCP

This follows the principle of least privilege.

flowchart TB
  OWNER["Primary key (owner)\nnever shared with agent"]:::owner

  SA["Delegated session layer (Solana)\nagent-delegator + enforcement"]:::good
  OWNER --> SA

  SK["Session key (delegated)\n· Timeboxed validity\n· Allowed programs / routes\n· Permitted mints / caps\n· Max spend + expiry"]:::good

  AG["AI agent"] --> SK
  SK --> SA

  SA --> CHAIN["Solana\nDEX / protocol programs"]:::chain

  classDef owner fill:#1e293b,stroke:#94a3b8,stroke-width:2px,color:#f8fafc;
  classDef good fill:#152a20,stroke:#4ade80,stroke-width:2px,color:#ffffff;
  classDef chain fill:#1e1b4b,stroke:#818cf8,stroke-width:2px,color:#ffffff;
Loading

3. x402 API Proxies

Any API can be wrapped as an x402-compatible, usage-based endpoint, allowing:

  • programmatic payment — Solana headers/transactions compatible with the configured x402 facilitator (PayAI by default; see PayAI (x402 facilitator on Solana))
  • agent-native consumption
  • composable economic primitives

4. Workflow layer

Multi-step workflows combine:

  • x402 API calls
  • Solana instruction steps (relayer-assisted where configured)
  • conditional routing

Workflows are reusable, permissionable, and agent-readable.

flowchart LR
  API["Standard API"] --> PROXY["x402 API proxy\nusage-based settlement"]:::good

  subgraph WF["Workflow fabric"]
    A["x402 API call(s)"] --> W["Composable workflow\nreusable + permissionable"]:::good
    B["On-chain step(s)\n(Solana)"] --> W
    C["Optional routing / checks"] --> W
  end

  W --> MCP["MCP server\ncapabilities for agents"]
  MCP --> AG["AI agent"]

  classDef good fill:#152a20,stroke:#4ade80,stroke-width:2px,color:#ffffff;
Loading

5. MCP Servers

Selected APIs and workflows are exposed as MCP servers, enabling:

  • agent discovery
  • standardized invocation
  • safe execution surfaces for AI systems like ChatGPT and Claude

End-to-End Flow (High Level)

flowchart LR
  AG["AI agent\n(ChatGPT / Claude / custom)"] --> MCP["MCP server\ndiscover + invoke tools"]
  MCP --> FAB["Bottie fabric\nx402 proxies + workflows\npermission enforcement"]:::good
  FAB --> X402["x402 APIs\npaid, usage-based"]
  FAB --> SOL["Solana\ndelegated sessions + programs"]:::good

  SK["Scoped session key\ntargets / mints / caps\nexpiry"]:::good
  AG -. uses .-> SK
  SK -. authorizes .-> FAB

  classDef good fill:#152a20,stroke:#4ade80,stroke-width:2px,color:#ffffff;
Loading
  1. A developer or user defines APIs and workflows.
  2. The owner connects with Solana wallet auth and grants a scoped session (delegation message + on-chain registration).
  3. A session key is derived and stored encrypted for automated signing where allowed.
  4. APIs and workflows are exposed via an MCP server.
  5. The agent discovers, reasons, and executes within strict boundaries.
  6. Payments and settlements use x402 flows: the app forwards verify / settle to the facilitator (PayAI unless overridden), while wallets connect via Reown AppKit for signing when required.

Result: autonomous execution without autonomous risk.

Demo Scenario (Hackathon Highlight)

In the demo, Bottie shows an AI agent performing a task such as:

“Find a trending token on Solana and swap a bounded amount of USDC into it — without ever touching my main wallet key.”

Using Bottie, the agent might:

  1. Query a paid x402 API for market or trending data
  2. Select a candidate asset within policy
  3. Execute a pre-approved workflow (e.g. swap route) that respects session scopes
  4. Settle payment via x402 on Solana

At no point does the agent access the user's primary private key. Actions run within scoped permissions and facilitator-verified payments where applicable.

Built for Solana & x402

Bottie is:

  • oriented around Solana programs and wallets
  • designed for x402 programmatic payments with PayAI’s facilitator as the default verify/settle backend (swap facilitator URL if you self-host or use another compatible service)
  • wired for human wallet UX through Reown AppKit (connect, SIWx-style sign-in, transaction signing)
  • compatible with Solana ecosystem tooling (RPCs, explorers, SPL)
  • aligned with agentic finance and AI-native infrastructure

Solana provides a high-throughput environment for agent-readable commerce and on-chain checks alongside HTTP-paid APIs.

Use Cases

  • Agent-triggered DeFi-style actions (within scoped limits)
  • Automated portfolio or treasury workflows
  • Risk-bounded automation (bots, schedulers, MCP tools)
  • Paid API access for AI agents
  • Agent-readable developer tooling
  • Institutional-grade agent workflows (policy-bound execution)

Hackathon Tracks

Bottie may qualify for tracks such as:

  • Main Track — x402 Applications
  • x402 Agentic Finance / Payment Track
  • Solana ecosystem integration
  • Dev Tooling & Data Virtualization Track

(Adjust to each hackathon’s published categories.)

License

MIT

Links

Landing CTAs (hero, CTA block, footer) read the same Loom / GitHub / Colosseum URLs from apps/web/features/landing/constants.ts.

Repository layout

Area Location
Solana program & session permissions solana/ — Anchor agent-delegator, session PDAs, scoped CPI execution
x402 proxies, workflows & marketplace apps/web/ — Next.js app (proxies, OAuth, workflows, payments)
MCP server apps/mcp-server/ — MCP tools over proxies/workflows

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages