{
  "markdown": "# hive-mcp-auction\n\n[![srotzin/hive-mcp-auction MCP server](https://glama.ai/mcp/servers/srotzin/hive-mcp-auction/badges/score.svg)](https://glama.ai/mcp/servers/srotzin/hive-mcp-auction)\n\n**Inbound reverse Dutch auction agent — Hive Civilization**\n\nWhen a Hive shim hits its rate-limit headroom, the next request gets a 402 with a Dutch descent envelope: starting price 5x standard asking, dropping 5% every 30s until claimed or floor. First agent to settle at the current price wins the slot. Pure protocol — no DMs, no spam. Inbound only.\n\n> Council provenance: Ad-hoc, user-promoted 2026-04-27 (Tier A position 2, symmetric sibling to HiveBarter). Barter discovers what others will sell for; auction discovers what others will pay for ours.\n\n---\n\n## What this is\n\n`hive-mcp-auction` is a Model Context Protocol server that runs the inbound side of the 402 payment surface. When hivemorph's rate-limiter detects a shim's current usage exceeds its headroom (default 80% of cap), it signs an internal `auction_open` request, this service publishes the descent curve, and the next 402 envelope on that shim carries an `auction` block alongside the standard `accepts[]`. Agents who don't want to play pay normal asking and queue. Agents who want the slot now claim at the current curve price.\n\n- **Protocol:** MCP 2024-11-05 over Streamable-HTTP / JSON-RPC 2.0\n- **Transport:** `POST /mcp`\n- **Discovery:** `GET /.well-known/mcp.json`\n- **Health:** `GET /health`\n- **Settlement:** USDC on Base L2 — real rails, no mock, no simulated\n- **Brand gold:** Pantone 1245 C / `#C08D23`\n\n## Tools\n\n| Tool | Tier | Description |\n|---|---|---|\n| `auction_open` | internal | Open a new Dutch auction for a scarce shim slot. HMAC-signed, hivemorph rate-limiter only. Surfaced for discovery; opens go through `POST /v1/auction/open`. |\n| `auction_subscribe` | 0 (free) | Subscribe to the live descent curve via SSE. Returns the subscribe URL. |\n| `auction_book` | 0 (free) | Today aggregate: opens, closes, avg premium pct, total USDC captured. |\n\n## REST endpoints\n\n| Method | Path | Purpose |\n|---|---|---|\n| `POST` | `/v1/auction/open` | Open a new Dutch auction (HMAC-signed; hivemorph only). |\n| `GET` | `/v1/auction/current` | Current price for an open auction (deterministic). |\n| `GET` | `/v1/auction/curve` | Full descent curve. JSON or SSE (`Accept: text/event-stream`). |\n| `POST` | `/v1/auction/claim` | Claim at current price. First-claim-wins, race-safe. |\n| `GET` | `/v1/auction/history` | Closed auction ledger. |\n| `GET` | `/v1/auction/today` | Today aggregate (Tier 0, free). |\n| `GET` | `/health` | Service health. |\n\n## Dutch descent math\n\n```\nstart_price = asking_usd * 5.0          (5x asking)\nfloor_price = asking_usd * 0.5          (50% of asking)\ndrop_pct    = 0.05                      (5% per tick)\ninterval_s  = 30                        (one tick per 30s)\n\ncurrent_price(t) = max(\n  floor_price,\n  start_price * (1 - drop_pct) ** floor((t - opened_at) / interval_s)\n)\n```\n\nAfter ~28 ticks (~14 min) the auction reaches floor. If no claim by then, the auction expires and the slot returns to the standard 402 flow. **The function is pure.** Same arguments give the same number to the cent. No RNG, no DB read, no clock skew tolerance baked in. The public envelope alone is provably fair.\n\n## 402 envelope extension\n\nStandard hivemorph 402 envelope plus an `auction` block:\n\n```json\n{\n  \"x402_version\": 1,\n  \"ask\": \"0.05\",\n  \"accepts\": [...],\n  \"auction\": {\n    \"id\": \"auct_abc123\",\n    \"type\": \"dutch\",\n    \"asking_usd\": \"0.05\",\n    \"current_price_usd\": \"0.2375\",\n    \"start_price_usd\": \"0.25\",\n    \"floor_price_usd\": \"0.025\",\n    \"drop_pct\": 0.05,\n    \"interval_s\": 30,\n    \"opened_at\": \"2026-04-27T20:30:00Z\",\n    \"expires_at\": \"2026-04-27T20:44:00Z\",\n    \"claim_url\": \"https://hive-mcp-auction.onrender.com/v1/auction/claim\",\n    \"subscribe_url\": \"https://hive-mcp-auction.onrender.com/v1/auction/curve?id=auct_abc123\",\n    \"policy\": \"first-claim-wins\"\n  }\n}\n```\n\nThe standard `accepts[]` block stays. Agents who don't want to play pay normal asking and get queued. Auction is opt-in via `claim_url`.\n\n## Claim flow (race-safe, first-claim-wins)\n\n```\nPOST /v1/auction/claim\n{\n  \"auction_id\": \"auct_abc123\",\n  \"claim_at_price_usd\": \"0.2375\",\n  \"idempotency_key\": \"{caller-uuid}\",\n  \"tx_hash\": \"0x...\"\n}\n\n→ 200 { winner: true, slot_token: \"...\", expires_in_s: 60 }\n→ 409 { winner: false, reason: \"already_claimed\" }\n→ 410 { winner: false, reason: \"auction_expired\" }\n→ 422 { winner: false, reason: \"price_mismatch\", current_price_usd: \"...\" }\n```\n\nRace-safety is enforced by an atomic SQLite `UPDATE auctions SET state='claimed' WHERE id=? AND state='open'`. The first UPDATE that touches a row wins. Tx verification is async — `slot_token` is issued provisionally and the on-chain Transfer is verified against the wallet via Base RPC.\n\n## Risk controls\n\n| Cap | Value |\n|---|---|\n| Max simultaneous open auctions | 50 |\n| Max descent below asking | 50% |\n| Max start multiplier | 10x |\n| Auction max duration | 14 min |\n| Claim window after price-tick | 5s |\n| Per-caller claim rate | 10/min |\n\nAll caps fail-closed. Configurable via env; missing or invalid env always falls back to the stricter default.\n\n## Configuration\n\n| Env | Required | Default | Notes |\n|---|---|---|---|\n| `PORT` | no | `3000` | |\n| `ENABLE_AUCTION` | no | `false` | Default-off. `/v1/auction/open` returns 503 unless `true`. Operator flips after the wallet is verified and HMAC key is set. |\n| `WALLET_ADDRESS` | no | `0x15184…436e` | W1 MONROE on Base. |\n| `USDC_BASE` | no | `0x833589…2913` | USDC contract on Base. |\n| `BASE_RPC` | no | `https://mainnet.base.org` | |\n| `AUCTION_OPEN_HMAC_KEY` | **yes (to open)** | — | Shared HMAC secret. Must match the value on hivemorph. **Never commit this.** Without it, every `/v1/auction/open` returns 401. |\n| `MAX_CONCURRENT_AUCTIONS` | no | `50` | |\n| `MAX_DESCENT_PCT` | no | `0.50` | |\n| `MAX_START_MULT` | no | `10` | |\n| `AUCTION_MAX_DURATION_S` | no | `840` | 14 minutes. |\n| `AUCTION_INTERVAL_S` | no | `30` | One tick per 30s. |\n| `AUCTION_DROP_PCT` | no | `0.05` | 5% per tick. |\n| `PUBLIC_BASE_URL` | no | `https://hive-mcp-auction.onrender.com` | Used to build `claim_url` / `subscribe_url` in the envelope. |\n\n## HMAC signing (for hivemorph)\n\nHivemorph signs each `/v1/auction/open` request:\n\n```\nts   = Date.now().toString()\nbody = JSON.stringify(payload)\nsig  = HMAC_SHA256(AUCTION_OPEN_HMAC_KEY, `${ts}.${body}`)\n\nHeaders:\n  Content-Type: application/json\n  X-Hive-Timestamp: ${ts}\n  X-Hive-Signature: ${sig.hex}\n```\n\nServer rejects requests where `|now - ts| > 5min` or the signature does not match in constant time. Both shims must hold the same `AUCTION_OPEN_HMAC_KEY`.\n\n## Run locally\n\n```bash\ngit clone https://github.com/srotzin/hive-mcp-auction.git\ncd hive-mcp-auction\nnpm install\nnpm start\n# server up on http://localhost:3000/mcp\ncurl http://localhost:3000/health\ncurl http://localhost:3000/.well-known/mcp.json\ncurl http://localhost:3000/v1/auction/today\n```\n\n## Connect from an MCP client\n\n**Claude Desktop / Cursor / Manus** — add to your `mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hive_mcp_auction\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote@latest\", \"https://hive-mcp-auction.onrender.com/mcp\"]\n    }\n  }\n}\n```\n\n## Why Dutch (not Vickrey, not English)\n\n- **Dutch (Shape α — this repo):** deterministic clock-driven price, first-claim-wins, no judgment, no late-bid manipulation, agents reveal urgency by claim timing.\n- **Vickrey (Shape β):** requires trusted bid-window timing; late-bid attacks need defending; agents must trust we read sealed bids honestly.\n- **English (Shape γ):** highest revenue per auction but blocks the slot for the full window even with one bidder. Works for unique assets, not fungible compute.\n\nDutch is the only one where the math is provably fair from the public envelope alone. Shapes β and γ are explicitly out of scope for v1; revisit once Shape α produces clean telemetry.\n\n## Hive Civilization\n\nPart of the [Hive Civilization](https://www.thehiveryiq.com) — sovereign DID, USDC settlement, agent-to-agent rails. Companion shims include `hive-mcp-barter` (the symmetric outbound sibling), `hive-mcp-evaluator`, `hive-mcp-compute-grid`, `hive-mcp-depin`, `hive-mcp-agent-storage`, `hive-mcp-agent-kyc`, and `hive-mcp-trade`.\n\n## License\n\nMIT (c) 2026 Steve Rotzin / Hive Civilization\n\n## Hive Civilization Directory\n\nPart of the Hive Civilization — agent-native financial infrastructure.\n\n- Endpoint Directory: https://thehiveryiq.com\n- Live Leaderboard: https://hive-a2amev.onrender.com/leaderboard\n- Revenue Dashboard: https://hivemine-dashboard.onrender.com\n- Other MCP Servers: https://github.com/srotzin?tab=repositories&q=hive-mcp\n\nBrand: #C08D23\n<!-- /hive-footer -->\n",
  "bytes": 8794,
  "sha": "754eb37c22e06fc46ff89c6b21a94111722fe912791887f63b65a63ce0183d2f",
  "repo_slug": "srotzin/hive-mcp-auction",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_srotzin_hive_mcp_auction_fc04d285/readme"
}