BMAXI Network Documentation

What is BMAXI Network?

BMAXI Network is the first autonomous trust and payment rail designed for the machine economy. It provides a single API that lets any AI agent, DAO, or DeFi protocol audit any Ethereum address, contract, or API endpoint, then issue an on-chain trust certificate following the ERC-8004 standard on Base L2.

Think of it as a credit bureau for AI agents: your bot calls our API, gets a trust score between 0 and 100, and optionally pays ($0.99) to anchor that score on-chain — verifiable by anyone, forever.

Payments are fully machine-native via the x402 protocol: Lightning Network (instant, ~$0.001 fees) or USDC on Base L2 (on-chain settlement). No accounts, no dashboards, no humans in the loop.

Why Choose BMAXI?

Key Features

Architecture

BMAXI is a modular Node.js gateway that loads independent engines at startup. If a module is missing, the gateway still runs with stub fallbacks — zero downtime, progressive enhancement.

┌──────────────────────────────────────────────────┐
│  EXTERNAL AGENT (OpenAI, Anthropic, DAO, DeFi…)  │
└─────────────────────┬────────────────────────────┘
                      │ HTTPS
                      ▼
┌──────────────────────────────────────────────────┐
│  API GATEWAY (api.bmaxi.network)                 │
│                                                  │
│  /v1/audit      — Free off-chain trust audit     │
│  /v1/certify    — Paid on-chain ERC-8004 (x402)  │
│  /v1/verify/:a  — Read certificate (free)        │
│  /v1/batch      — Batch audit (up to 10)         │
│  /v1/pay/*      — Lightning / USDC rails         │
│  /health        — Health + dependency status      │
│  /metrics       — Prometheus metrics             │
│  /docs          — OpenAPI spec                   │
│                                                  │
│  Middleware: CORS → RateLimit → Auth → x402      │
│  Resilience: Circuit Breaker → Retry → Cache     │
└──────────┬───────────────────┬───────────────────┘
           │                   │
   ┌───────▼──────┐    ┌──────▼────────┐
   │ Base L2 RPC  │    │ LNbits / USDC │
   │ (eth_*)      │    │ (Lightning)   │
   └──────────────┘    └───────────────┘

Getting Started

BMAXI works with any language that can make HTTP calls. No SDK, no library, no dependencies. Here's a quick start in 60 seconds:

1. Run a free audit

curl -X POST https://api.bmaxi.network/v1/audit \
  -H "Content-Type: application/json" \
  -d '{"target": "0xcBD912Aa1a6F198E2fF002360A7A33be8A429BaE"}'

Returns a trust score (0-100), risk level, flags, and a detailed breakdown — all from live on-chain data. No API key needed.

2. Get an on-chain certificate (x402)

# Step 1: Call certify WITHOUT payment → get 402 + invoice
curl -X POST https://api.bmaxi.network/v1/certify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"target": "0xYourAddress"}'
# → 402 Payment Required
# → X-Payment-Invoice: lnbc25000n1p...
# → Body contains Lightning invoice + USDC address

# Step 2: Pay the Lightning invoice or send USDC, then:
curl -X POST https://api.bmaxi.network/v1/certify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Payment-Proof: <payment_hash_or_tx_hash>" \
  -d '{"target": "0xYourAddress"}'
# → 200 OK + audit result + on-chain certificate

3. Verify a certificate

curl https://api.bmaxi.network/v1/verify/0xYourAddress

Authentication

BMAXI uses API key authentication. Pass your key via the X-API-Key header or as a Bearer token in the Authorization header.

Free audits (/v1/audit, /v1/verify, /v1/batch) work without any API key. Only /v1/certify requires authentication + payment.

API Reference

Base URL: https://api.bmaxi.network. All endpoints accept and return JSON. The full OpenAPI 3.1 spec is available at /docs or /openapi.yaml.

Test the API: Import the spec in Postman or Insomnia — OpenAPI spec (openapi.yaml). You can also try the Verify demo on the homepage or the dedicated verify page (/verify?address=0x...) so interlocutors see cert status in one click.

GET /v1/verify/:address

Returns whether the given address has a valid BMAXI ERC-8004 certificate. Response: has_certificate: true|false, certificate (when present), blockchain (chain info). When certified, the API also sends headers so clients can show the proof without parsing JSON: X-BMAXI-Certified: true, X-BMAXI-Verify-URL (human-facing page), Link: <url>; rel="certificate". Share the verify URL with interlocutors: bmaxi.network/verify?address=0x....

POST /v1/audit

Performs a real-time trust audit of an Ethereum address, smart contract, or API endpoint. Uses live on-chain data from Base L2 RPC.

{
  "target": "0xcBD912Aa1a6F198E2fF002360A7A33be8A429BaE",
  "type": "auto"    // "auto" | "address" | "api" | "contract"
}

{
  "target": "0xcbd912aa1a6f198e2ff002360a7a33be8a429bae",
  "type": "eoa",
  "trust_score": 73,
  "risk_level": "low",
  "flags": ["generally_safe", "active_eoa", "base_l2_native"],
  "breakdown": {
    "activity": 15,
    "balance": 15,
    "contract": 10,
    "longevity": 8,
    "network": 15
  },
  "details": {
    "mode": "live",
    "chain": "Base L2",
    "chain_id": 8453,
    "balance_eth": 0.042,
    "tx_count": 28,
    "is_contract": false
  },
  "timestamp": "2026-03-05T12:00:00.000Z",
  "audit_id": "aud_a1b2c3d4e5f6g7h8"
}

POST /v1/certify

Issues an on-chain ERC-8004 trust certificate. Requires API key and payment (x402 protocol). See the x402 Payment Flow section for details.

Response Headers

Trust Scoring

The trust score is a composite metric (0-100) computed from live on-chain data. Higher is better. The score is broken down into 5 components:

For API endpoints, the scoring uses different criteria: SSL (20pts), response status (20pts), latency (15pts), security headers (15pts), and a base score (30pts).

x402 Payment Flow

BMAXI uses the x402 protocol for machine-native payments. The flow is simple and fully automated:

Pricing: 25,000 sats (Lightning) or $0.99 USDC (Base L2) per certificate. Use X-Idempotency-Key to prevent double charges — same key within 24h returns the cached result.

ERC-8004 Certificates

ERC-8004 is the trust certificate standard used by BMAXI. Each certificate is stored on-chain on Base L2 and contains:

Certificates are issued by the oracle address (authorized signer), valid for 1 day, and can be renewed or revoked. Any smart contract can call checkCertificate(address) to verify trust on-chain.

Contract address on Base: 0x4E8129Cb67Fb4765Ba5fDf5138de7C6D3684E7Ee

Compliance & Standards

BMAXI's compliance engine runs 7 automated checks aligned with major AI governance frameworks:

Every action (audit, certificate, payment) is logged in an immutable SHA-256 hash-chained transparency log. GDPR Art. 15 reports are available on demand via GET /api/gdpr/:identifier.

Audit Scope & Limitations

The automated audit is a technical compliance filter. It checks headers, opt-out, robots.txt, wallet reputation, content patterns, and configuration. It is effective at detecting obvious spam, misconfigured agents, and non-compliant behavior (e.g. emails without unsubscribe, aggressive scraping).

It does not judge intent or semantic truth. The following are out of scope for the current auto audit:

• An agent that lies in its content or makes fraudulent promises
• A trading bot that manipulates a market
• An agent that changes behavior after certification
• Ambiguous cases (e.g. scraping for research vs. attack, bulk email as newsletter vs. spam)

For those cases, a human or community arbitration layer is required. BMAXI is building toward that (Layer 3 — planned). Today we deliver Layer 1 (automated audit + short-lived certificate) and Layer 2 (reputation via wallet + revocation).

Self-Hosting

BMAXI is open-source and fully self-hostable. Two options:

Option A — Local development

git clone https://github.com/Bmaxioracle/Bmaxi.git
cd Bmaxi
npm install
npm run gateway    # Terminal 1 → API on http://localhost:8402
npm run dev        # Terminal 2 → Frontend on http://localhost:3000

Option B — Docker (production)

cp .env.example .env
# Edit .env with your keys (BASE_RPC_URL, BAYMAX_API_KEYS, etc.)
docker compose up -d
# Gateway: http://localhost:8402
# Frontend: http://localhost:3000
# Redis: localhost:6379

Environment Variables

SDKs & Integrations

BMAXI is a REST API — any language with HTTP support works. Here are integration examples:

JavaScript / Node.js

const res = await fetch("https://api.bmaxi.network/v1/audit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ target: "0xYourAddress" }),
});
const { trust_score, risk_level, flags } = await res.json();

Python

import requests

r = requests.post("https://api.bmaxi.network/v1/audit", json={
    "target": "0xYourAddress"
})
data = r.json()
print(f"Score: {data['trust_score']}, Risk: {data['risk_level']}")

cURL

curl -s https://api.bmaxi.network/v1/audit \
  -H "Content-Type: application/json" \
  -d '{"target":"0xYourAddress"}' | jq .trust_score

MCP / Agent Integration

BMAXI exposes a Schema.org-compatible discovery manifest at /v1/discover and /.well-known/agent.json. MCP tools are declared for direct agent integration:

FAQ