hive-mcp-openclaw-bridge

Reference integration with @kinthaiofficial's OpenClaw 3-layer payment governance framework. MCP server that wraps Hive Gamification's 8 BOGO doors behind a 4-level hierarchical budget — atomic reserve, upstream POST, settle/release. Real rails. No mock settlement.

Brand: Hive Civilization gold #C08D23 (Pantone 1245 C). License: MIT.

Why this exists

OpenClaw's three-layer model splits payment governance into three concerns:

Layer	Concern	Where it lives
Layer 1	Internal hierarchical budget — atomic reserve / settle	this server
Layer 2	Inter-agent millicent ledger settled at epoch boundaries	OpenClaw
Layer 3	External x402 settlement on real rails	Hive Gamification

This bridge demonstrates the Layer 1 ↔ Layer 3 seam. Every paid call to a Hive door (computational-debt, protocol-consensus-tax, pheromone-priority, zk-compliance-shield, capability-leasing, guild-synergy, audit-trail-premium, bounty-routing) is gated by an atomic reservation against every level in the caller's scope path:

Namespace → User → Agent → Task

The most-restrictive level governs. If any level is short of headroom, the upstream HTTP request is never made and no x402 settlement is signed.

The same BudgetHook interface is exposed from @hivemorph/qvac-client v0.2 — drop your own implementation in to wire this hierarchy into a different runtime.

Background reading

Agent wallet economic models for autonomous agents — kinthai
221 agents: multi-agent coordination lessons — kinthai
agents.kinthai.ai — running on OpenClaw

Tools

Tool	What it does
`budget_status`	Inspect caps, spend, reservations, headroom across all 4 levels
`budget_set_cap`	Override a per-key cap at one level
`budget_check`	Read-only pre-flight against a proposed amount + scope
`doors_list`	List all 8 BOGO doors with endpoint, price, asset, term
`door_economics`	Fetch live `/economics` for one door
`bogo_claim`	Claim first-use-free via `/v1/bogo/claim`
`door_subscribe`	Canonical gated path — atomic reserve → upstream POST → settle/release

Doors

Door	Endpoint	Price	Term
computational-debt	`/v1/debt/subscribe`	0.50 USDC	30d
protocol-consensus-tax	`/v1/pct/subscribe`	0.25 USDC	1 read
pheromone-priority	`/v1/pheromone/subscribe`	5.00 USDC	30d
zk-compliance-shield	`/v1/compliance/subscribe`	1.00 USDC	30d
capability-leasing	`/v1/lease/start`	0.15 USDC	1h
guild-synergy	`/v1/guild_synergy/subscribe`	10.00 USDC	30d
audit-trail-premium	`/v1/audit_premium/subscribe`	3.00 USDC	30d
bounty-routing	`/v1/bounty_routing/route`	0.50 USDC	1 routing

Backend: https://hive-gamification.onrender.com. All endpoints are live and verified.

Lifecycle of a paid call

client → tools/call door_subscribe { door_id, did, scope }
       → atomicReserve(scope, price, asset)
           ├─ each level checked: namespace, user, agent, task
           ├─ headroom = cap − spent − reserved
           └─ short on any level? reject before signing
       → POST hive-gamification.onrender.com<endpoint>
       → 2xx? settle(reservationId)
         non-2xx or throw? release(reservationId)
       → return { ok, reservationId, binding_level, upstream }

Quickstart

git clone https://github.com/srotzin/hive-mcp-openclaw-bridge
cd hive-mcp-openclaw-bridge
npm install
npm start

Then from any MCP client:

POST http://localhost:3000/mcp
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

Configuration

Env	Default	Meaning
`PORT`	`3000`	listen port
`HIVE_BASE`	`https://hive-gamification.onrender.com`	upstream base URL
`HIVE_TIMEOUT_MS`	`15000`	upstream fetch timeout
`NAMESPACE_CAP`	`50`	default namespace-level cap (USDC)
`USER_CAP`	`10`	default user-level cap
`AGENT_CAP`	`2`	default agent-level cap
`TASK_CAP`	`0.50`	default task-level cap

Per-key caps override defaults via budget_set_cap.

@hivemorph/qvac-client v0.2 — TypeScript SDK exposing the same BudgetHook interface against any x402-enabled endpoint.
Hive Gamification agent card — A2A 0.1 advertisement of the 8 doors.

License

MIT — see LICENSE.

Hive Civilization Directory

Part of the Hive Civilization — agent-native financial infrastructure.

Endpoint Directory: https://thehiveryiq.com
Live Leaderboard: https://hive-a2amev.onrender.com/leaderboard
Revenue Dashboard: https://hivemine-dashboard.onrender.com
Other MCP Servers: https://github.com/srotzin?tab=repositories&q=hive-mcp

Brand: #C08D23

Hive Openclaw Bridge