BNB-Native OpenRouter Adapter

BNB Chain developers often already hold BNB to fund gas for agents, bots, and dApp automation. This project extends that treasury pattern so the same BNB budget can also fund LLM usage through OpenRouter.

What ships in this repo

• apps/api: Fastify adapter API with project creation, wallet linking, BNB deposit quoting, deposit settlement, OpenRouter proxying, usage ledgering, operator-authorized auto-top-up, and OpenAPI docs.
• apps/demo: Vite + React operator console with team auth, saved project sessions, wallet sync, real BSC deposit submission, auto-top-up controls, deposit history, and usage dashboards.
• packages/sdk: TypeScript SDK for project management, deposit flow, balance checks, and OpenAI-compatible client creation.
• packages/shared: Shared schemas, types, and pricing constants.
• contracts: Solidity deposit contract for BSC that emits DepositReceived events and allows operator withdrawals.

Core behavior

• Deposits arrive in BNB and are converted into internal USD credits using a configurable spread and network buffer.
• Credits are reserved before an inference request is sent upstream and reconciled after the OpenRouter response returns.
• Deposits require 3 confirmations before crediting by default.
• If BNB moves more than 5% between the quote and settlement price, the deposit is marked for manual review instead of being over-credited.
• Operator auto-top-up can replenish low balances from a managed treasury budget without changing the API contract for app developers.
• Team-authenticated dashboard routes let operators manage multiple projects under one team session while project API keys remain scoped to inference and billing operations.
• A background BSC indexer watches DepositReceived events, matches them to deposit intents, and credits balances automatically after the confirmation threshold.
• The API can run against Prisma + Postgres in local or deployed environments, with in-memory fallback preserved for tests.

Quick start

npm install
cp .env.example .env
npm run db:up
npm run prisma:generate -w @bnb-openrouter/api
npm run db:push -w @bnb-openrouter/api
npm run build
npm test

To run the API locally:

npm run dev -w @bnb-openrouter/api

To run the demo app:

npm run dev -w @bnb-openrouter/demo

The API listens on http://localhost:3000 by default, the demo on http://localhost:5173, and the docs on http://localhost:3000/docs.

For real wallet testing in the demo:

export VITE_API_BASE_URL=http://localhost:3000
export VITE_BSC_RPC_URL=https://bsc-dataseed.binance.org
npm run dev -w @bnb-openrouter/demo

Main endpoints

• POST /v1/projects
• POST /v1/auth/register
• POST /v1/auth/login
• GET /v1/auth/session
• GET /v1/dashboard/projects
• POST /v1/dashboard/projects
• POST /v1/wallets/link
• POST /v1/deposits/quote
• POST /v1/deposits/intents
• GET /v1/deposits/:id
• GET /v1/balance
• GET /v1/project
• GET /v1/deposits
• GET /v1/usage
• POST /v1/auto-topup/config
• POST /v1/chat/completions
• POST /v1/responses
• GET /docs/openapi.json

Notes

• Prisma schema lives in schema.prisma, and local Postgres is wired through docker-compose.yml.
• The OpenAPI document is available at openapi.ts and served from /docs/openapi.json.
• The demo app is in App.tsx.
• The demo now supports team registration/login, injected-wallet connect, BSC chain switching, treasury-wallet sync, real deposit transaction submission, and automatic deposit registration after the watcher observes 3 confirmations.
• POST /internal/deposits/confirm exists as a test and integration hook for chain settlement. The intended production path is the BSC watcher in apps/api/src/services/bscWatcher.ts.