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

Two backends, one contract

The demo agent and the live RobinX agent return the same reply shape. If the live agent fails, times out, or returns an invalid shape, the response falls back to demo rather than breaking the UI — so a missing key degrades the answer, never the app.

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 tool, a timeout, or a malformed reply degrades to the demo agent with source: "demo". The user gets a worse answer, never a broken page.

The agent never holds your keys

Read tools run server-side. Write and trade tools compile to an unsigned transaction your wallet signs. There is no custody path, so there is no key to steal from us.

Simulate before signature

Every state-changing call is dry-run against live chain state first, and the UI shows exactly what leaves your wallet. Approval drains and honeypot sells are caught while walking away is still free.

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

• Demo mode — API reachable, no live credentials.
• 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