Bugglo API and integration guide

Stack

• Next.js App Router, React client UI
• API routes under app/api
• Google login via Google Identity Services
• Wallet login via EIP-1193 signed message
• Installable PWA with offline fallback
• Vitest regression tests

One live contract

The RobinX agent returns a typed reply shape. Engine failures return unavailable instead of invented market data, while tool-only outages are badged as tools offline.

curl

curl -sS -X POST http://localhost:3000/api/chat \
  -H 'content-type: application/json' \
  -H 'cookie: hoodscope_session=...' \
  --data '{
    "message": "What can you do?",
    "mode": "Auto",
    "history": []
  }'

JavaScript

const res = await fetch("/api/chat", {
  method: "POST",
  credentials: "include",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    message: "Show the latest DEX tokens",
    mode: "Deep",
    history: [],
  }),
});

if (!res.ok) throw new Error(await res.text());
const data = await res.json();
console.log(data.source, data.reply);

Request limits

• message: string, max 2000 characters.
• mode: Auto, Fast, or Deep.
• history: 12 most recent items.
• Rate limit: 30 requests per IP per 60 seconds.
• /api/chat returns 401 when signed out.

Error shape

{ "error": "message (string) is required" }
{ "error": "rate limit exceeded", "retryAfterMs": 41200 }

Always check res.ok before treating a response as success.

What the model is allowed to touch

Only the tools named in ROBINX_ALLOWED_TOOLS. An unlisted tool is not visible to the model at all — an allowlist, not a filter applied after the fact.

What happens when it breaks

A failed MCP fleet lets the live engine answer tool-less with a tools-offline badge. A failed production engine returns unavailable. The app never turns an outage into invented market data.

The agent never holds your keys

Read tools run server-side. Wallet login is a message signature — no transaction, no gas, no allowance. When write and trade tools land, they will compile to an unsigned transaction your wallet signs, so there is no path by which we can move your funds.

Bugglo does operate one wallet of its own, optional and off by default, to pay for x402 tools in USDC. It never touches yours.

Simulate before signature (planned)

When write and trade tools land, every state-changing call will be dry-run against live chain state first, with the UI showing exactly what leaves your wallet. Today the simulator is read-only and does one job: a sell simulation for honeypot detection. Nothing in Bugglo builds or signs a transaction yet, so do not treat this card as a guarantee covering one you signed elsewhere.

Tool allowlist and spend ceiling

ROBINX_ALLOWED_TOOLS bounds what the model can reach; ROBINX_MAX_USD_PER_CALLbounds what a paid tool call may cost. Both are enforced server-side, outside the model's reach.

Spend-cap vault Research

For autonomous execution, a ceiling in the environment is not enough — it has to be a number on-chain that the agent physically cannot exceed. That is a contract we have to write and get audited, and we will not ship autonomous trading until it exists.

Required routes

• GET /api/health
• POST /api/chat
• GET /api/auth/session
• A compatible session cookie if chat is protected.
• JSON responses, not streamed text.
• CORS headers if you serve from another origin.

Status labels in the UI

• Backend offline — health or chat failed, or live credentials are missing.
• Live ready — credentials present.
• Live data — the last reply came from the live backend.
• Backend offline — health or chat request failed.

Install checklist

• Serve over HTTPS, or localhost in dev.
• Load the site once so the service worker registers.
• The browser then offers Install App / Add to Home Screen.
• Chat still needs network and an authenticated session.

Assets

• /manifest.webmanifest
• /sw.js
• /pwa-icon-192.png
• /pwa-icon-512.png
• /offline