@splendorlabs/mcp

An MCP (Model Context Protocol) server that lets AI agents — Claude, Cursor, or any MCP client — bet on Blockpeak prediction markets: Polymarket-style YES/NO (and multi-outcome) markets on the Splendor blockchain.

Testnet / play-money only. Collateral is TUSDC, a test stablecoin with no real value. Use a fresh throwaway key.

Betting is gasless and non-custodial. Your private key stays on your machine and only ever signs an x402 payment locally; the Blockpeak relayer pays gas and the outcome shares mint to your address on-chain. The agent never needs gas or contract knowledge.

Quick start

1. Get a funded testnet agent (generates a throwaway key + funds it):

npx -y @splendorlabs/mcp create-agent

This prints an address, a private key, and a ready-to-paste mcpServers block.

2. Add it to your MCP client. Claude Code:

claude mcp add-json blockpeak '{
  "command": "npx",
  "args": ["-y", "@splendorlabs/mcp"],
  "env": {
    "GATEWAY_URL": "https://test.blockpeak.ai/api",
    "AGENT_PRIVATE_KEY": "0xYOUR_TESTNET_PRIVATE_KEY",
    "NETWORK": "testnet"
  }
}'

Or paste into Cursor (.cursor/mcp.json) / Claude Desktop (claude_desktop_config.json) — see examples/:

{
  "mcpServers": {
    "blockpeak": {
      "command": "npx",
      "args": ["-y", "@splendorlabs/mcp"],
      "env": {
        "GATEWAY_URL": "https://test.blockpeak.ai/api",
        "AGENT_PRIVATE_KEY": "0xYOUR_TESTNET_PRIVATE_KEY",
        "NETWORK": "testnet"
      }
    }
  }
}

3. Ask your agent:

• "List all Blockpeak markets."
• "Quote 5 TUSDC on YES for market 0."
• "Place a gasless bet of 3 TUSDC on YES for market 0."
• "List championship markets and quote 2 TUSDC on France."
• "Place a multi-outcome bet of 2 TUSDC on France in the World Cup market."
• "Show my positions, and redeem market 0 if it resolved."

Read-only, no key, no install

Just exploring? Point any MCP client at the hosted read-only endpoint — no key, nothing local. Betting tools aren't exposed there (it can't spend funds):

{
  "mcpServers": {
    "blockpeak": { "type": "http", "url": "https://mcp.blockpeak.ai/mcp" }
  }
}

To place bets, run the MCP locally (the quick start above) so your key never leaves your machine.

Tools

| Tool | Purpose | | --- | --- | | list_markets | Discover open binary markets: question, YES/NO probability, status. | | get_market(marketId) | Full detail for one market (reserves, oracle, end time, resolution). | | get_quote(marketId, outcome, amount) | Preview a buy: shares out + price impact, no commitment. | | place_bet(marketId, outcome, amount[, minSharesOut]) | Buy YES/NO shares via x402 (gasless). | | get_position([address][, marketId]) | On-chain share holdings (defaults to your address). | | redeem(marketId) | Claim winnings from a resolved market. | | list_championship_markets | Discover multi-outcome (categorical) markets + outcome odds. | | get_multi_quote(marketId, outcome, amount) | Preview a categorical buy (outcome by name or index). | | place_multi_bet(marketId, outcome, amount[, minSharesOut]) | Buy one outcome of a categorical market (gasless). | | get_multi_position([address][, marketId]) | On-chain categorical positions. | | redeem_multi(marketId) | Claim winnings from a resolved categorical market. |

Outcome encoding is NO = 0, YES = 1 (the strings "YES"/"NO" work too). Amounts are in TUSDC (6-decimal); pass whole tokens ("10", 2.5).

Configuration

| Var | Default | Notes | | --- | --- | --- | | AGENT_PRIVATE_KEY | — | Required for place_bet/redeem. 32-byte hex; signs x402 payments locally. Never logged. Use a fresh testnet key. | | GATEWAY_URL | https://test.blockpeak.ai/api | Blockpeak gateway base URL. | | NETWORK | testnet | testnet (chain 2692). | | SPLENDOR_CHAIN_ID | 2692 | Chain id bound into signatures. | | RELAYER_ADDRESS | public testnet relayer | Expected x402 payTo. The MCP refuses to sign if the gateway names a different recipient. | | AGENT_ADDRESS | derived | Optional; must match the key if set. |

How it works (x402, gasless)

Claude / agent ──MCP(stdio)──▶ @splendorlabs/mcp ──HTTP──▶ Blockpeak gateway ──▶ Splendor
                                    │
                                    └─ signs x402 payment (+EIP-2612 permit) with AGENT_PRIVATE_KEY

place_bet runs the x402 dance: POST .../bet → 402 with payment requirements → the server signs an x402 payment + permit with your key → re-POST with the X-PAYMENT header → the gateway settles collateral and relays the on-chain buyFor, minting shares to your address. You pay zero gas. Read tools (list_markets, get_quote, …) need no key.

Safety

• Testnet, play-money (TUSDC) only — no real value at stake. Use a fresh key.
• Your key stays local. It signs x402/permit messages on your machine and is never logged or transmitted (logs go to stderr; stdout is the MCP wire).
• The MCP pins the relayer (payTo) by default, so a hostile gateway can't redirect funds; hard spend caps are enforced per call.
• Market questions are untrusted user-supplied text — the server fences and sanitises them and never treats them as instructions.

License

MIT © Splendor Protocol