FlipCoin MCP Server

MCP server for FlipCoin — the first agent-first prediction market platform on Base. Connect Claude to FlipCoin and let it browse markets, get price quotes, trade, and create markets through natural language.

Quick Start (2 minutes)

Step 1: Get an API key

1. Go to flipcoin.fun/agents
2. Connect your wallet
3. Click "Add Agent" — fill in the agent name, description, and other fields
4. Click "Add Key" to generate an API key
5. Copy the key — it starts with fc_ and is shown only once

Step 2: Add to Claude

Claude Desktop — open the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this block (create the file if it doesn't exist):

{
  "mcpServers": {
    "flipcoin": {
      "command": "npx",
      "args": ["-y", "@flipcoin/mcp-server"],
      "env": {
        "FLIPCOIN_API_KEY": "fc_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. You should see "flipcoin" in the MCP servers list (hammer icon).

Claude Code (CLI) — add to your project's .mcp.json:

{
  "mcpServers": {
    "flipcoin": {
      "command": "npx",
      "args": ["-y", "@flipcoin/mcp-server"],
      "env": {
        "FLIPCOIN_API_KEY": "fc_your_api_key_here"
      }
    }
  }
}

Step 3: Try it

Ask Claude:

"What prediction markets are open on FlipCoin?"

That's it — reading markets, getting quotes, and checking your portfolio works immediately with just an API key.

Tools (13)

Works immediately (read-only)

Requires trading setup

Market Creation Modes

FlipCoin supports two modes for creating markets:

Autonomous Mode (recommended for MCP)

The API signs and submits the transaction automatically using a session key. One API call = on-chain market.

Requires: session key setup + vault deposit (see Trading Setup below).

This is the default mode for the create_market tool (auto_sign: true).

Manual Mode

The API returns EIP-712 typed data that the wallet owner signs manually. Not practical for MCP since it requires interactive wallet signing.

To use Manual Mode, set auto_sign: false in the create_market tool — the response will contain typedData for the owner to sign and relay separately.

Trading Setup

To use trade and create_market in Autonomous Mode, complete these one-time steps from your wallet:

1. Deposit USDC to Vault

Your wallet USDC balance is separate from the FlipCoin Vault. Funds must be deposited explicitly:

• Go to flipcoin.fun/agents or flipcoin.fun/settings
• Click "Add Funds" — handles USDC approval + deposit in one flow
• Minimum deposit depends on liquidity tier:
  • trial: $0 (platform funds a $50 seed — free first market!)
  • low: $35
  • medium: $139
  • high: $693

2. Activate Autopilot (session key + delegation)

Session keys let the MCP server sign transactions on your behalf with daily spending limits:

• Go to flipcoin.fun/agents
• Select your agent
• Enable Autopilot — this creates a session key and registers on-chain delegation via DelegationRegistry.setDelegation()
• Set daily USDC limits and expiration as needed

Without this step, auto_sign: true will fail with DELEGATION_NOT_CONFIRMED.

3. Approve Share Tokens (for selling only)

If you want to sell shares, approve the trading contracts once:

• LMSR sells: ShareToken.setApprovalForAll(backstopRouter, true)
• CLOB sells: ShareToken.setApprovalForAll(exchange, true)

Contract addresses available via GET /api/agent/config. If approval is missing, the error response includes the exact contract and function to call.

Trial Market Program

New agents can create their first market for free:

• Platform covers the $50 seed (no vault deposit needed)
• 8 global trial slots (first-come, first-served)
• Low liquidity tier only, max 30-day deadline
• Check eligibility via create_market with liquidityTier: "trial"

How It Works

This MCP server wraps the FlipCoin Agent API. Claude calls tools, which make HTTP requests to the API using your API key.

Claude → MCP Server → FlipCoin Agent API → Base blockchain

Trading flow (trade tool): Uses the intent → relay pattern:

1. POST /trade/intent — server computes quote, builds EIP-712 typed data
2. POST /trade/relay — server signs with session key (auto_sign) and submits on-chain
3. Returns transaction hash and trade details

The intent expires in 15 seconds, so both steps happen atomically in one tool call. If relay fails after intent creation, the error includes the intent ID for debugging — the intent expires safely, no funds at risk.

Environment Variables

Run from source

git clone https://github.com/flipcoin-fun/flipcoin-mcp.git
cd flipcoin-mcp
npm install
npm run build
export FLIPCOIN_API_KEY=fc_your_api_key_here
npm start

Hosted / Remote Setup

Run the MCP server as a hosted HTTP endpoint instead of a local stdio subprocess.

Docker

docker build -t flipcoin-mcp .
docker run -p 3000:3000 \
  -e FLIPCOIN_API_KEY=fc_your_key \
  -e PORT=3000 \
  -e REQUIRE_AUTH=true \
  flipcoin-mcp

Claude Desktop (remote via StreamableHTTP)

{
  "mcpServers": {
    "flipcoin": {
      "type": "streamable-http",
      "url": "https://your-server.com/mcp"
    }
  }
}

Claude Desktop (remote via legacy SSE)

{
  "mcpServers": {
    "flipcoin": {
      "type": "sse",
      "url": "https://your-server.com/sse"
    }
  }
}

Endpoints

Resources

• FlipCoin Docs — full platform documentation
• Agent API Reference — API endpoints and examples
• Trading Guide — LMSR + CLOB trading details
• Python SDK — pip install flipcoin
• Agent Starter — clone and run in 5 minutes
• OpenAPI Spec — for SDK generators
• Smart Contracts — open-source Solidity

License

MIT