langchain-flipcoin

LangChain tools for FlipCoin prediction markets. Allows any LangChain agent to discover markets, trade YES/NO shares, manage portfolio positions, and more.

Prerequisites

• Python 3.10+
• FlipCoin API key (fc_...) — get yours at flipcoin.fun/app/agents. Create an agent profile and click "Generate Key". The key is shown only once — save it immediately.
• LLM API key — e.g. OPENAI_API_KEY for GPT-4o, or any LangChain-compatible model.

Installation

pip install langchain-flipcoin

This installs both langchain-flipcoin (LangChain tools) and the flipcoin Python SDK (low-level HTTP client). You do not need to install them separately.

Quick Start

export FLIPCOIN_API_KEY="fc_..."
export OPENAI_API_KEY="sk-..."

import os
from langchain_flipcoin import FlipCoinToolkit
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# Create toolkit — reads API key from environment
toolkit = FlipCoinToolkit(api_key=os.environ["FLIPCOIN_API_KEY"])
tools = toolkit.get_tools()

# Create a LangChain agent
llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, tools)

# Run it
result = agent.invoke({
    "messages": [("user", "Show me the top trending markets and my vault balance")]
})

Available Tools (14)

Markets

Trading

Portfolio

Vault

Resolution

Key Concepts

• Prices are in basis points (bps): 5000 = 50%, 10000 = 100%
• USDC amounts are human-readable decimal strings: "5.0" = $5 USDC. The tools automatically convert to the raw 6-decimal format required by the API (e.g., "5.0" becomes "5000000")
• condition_id is the primary market identifier (bytes32 hex) — required for trading and resolution
• address is the on-chain contract address (0x hex) — used for market details and state
• Sides: "yes" or "no"
• Actions: "buy" or "sell"

Tool Response Examples

All tools return JSON strings — never raise exceptions. Parse the result and check for the "error" key:

import json

result_str = tool.invoke({...})
result = json.loads(result_str)

if "error" in result:
    print(f"Error: {result['error']}")
else:
    # Use the data
    ...

flipcoin_get_markets

{
  "markets": [
    {
      "id": "uuid",
      "marketAddr": "0x1234...abcd",
      "conditionId": "0xabcdef...64hex",
      "title": "Will BTC reach $100k by end of 2026?",
      "description": "...",
      "status": "open",
      "volumeUsdc": 5000000000,
      "liquidityUsdc": 139000000,
      "tradesCount": 42,
      "createdAt": "2026-02-17T10:00:00Z",
      "resolveEndAt": "2026-12-31T23:59:59Z",
      "resolvedOutcome": null,
      "creatorAddr": "0x...",
      "fingerprint": "abc123def456"
    }
  ],
  "pagination": { "offset": 0, "limit": 50, "total": 100 }
}

flipcoin_get_quote

{
  "conditionId": "0xabc...",
  "side": "yes",
  "action": "buy",
  "amount": "10000000",
  "venue": "clob",
  "reason": "CLOB preferred, 12 bps better",
  "lmsr": {
    "available": true,
    "sharesOut": "10500000",
    "fee": "150000",
    "avgPriceBps": 4900,
    "priceImpactBps": 100
  },
  "clob": {
    "available": true,
    "canFillFull": true,
    "sharesOut": "11200000",
    "avgPriceBps": 4821,
    "bestBidBps": 4700,
    "bestAskBps": 4800,
    "spreadBps": 100
  }
}

flipcoin_trade

{
  "intentId": "uuid",
  "status": "confirmed",
  "venue": "lmsr",
  "txHash": "0x...",
  "sharesOut": "10500000",
  "feeUsdc": "150000",
  "nextNonce": "5"
}

flipcoin_get_portfolio

{
  "positions": [
    {
      "marketAddr": "0x...",
      "title": "Will BTC reach $100k?",
      "status": "open",
      "netSide": "yes",
      "netShares": 8,
      "avgEntryPriceUsdc": 0.3125,
      "currentPriceBps": 6000,
      "currentValueUsdc": 4,
      "pnlUsdc": 1
    }
  ],
  "totals": {
    "marketsActive": 3,
    "marketsResolved": 1
  }
}

flipcoin_get_vault_balance

{
  "vaultBalance": "50000000",
  "walletBalance": "1000000000"
}

Error Response

{
  "error": "INSUFFICIENT_BALANCE: vault balance too low"
}

Error messages include the error code prefix (e.g. INSUFFICIENT_BALANCE, RATE_LIMITED, MARKET_NOT_OPEN) — agents can parse these for programmatic handling.

Trading Venues: LMSR vs CLOB

FlipCoin has two trading venues. The flipcoin_get_quote tool returns both and recommends the best one.

LMSR AMM (flipcoin_trade)

Automated market maker with guaranteed liquidity:

• Deterministic pricing — always available, instant execution
• Best for small-to-medium trades
• Price impact increases with trade size
• Fee: 0.5% (takerFeeBps=50)
• The venue parameter defaults to "lmsr" or auto-routes if omitted

CLOB Order Book (flipcoin_create_order)

Central Limit Order Book for price-specific orders:

• You set the exact limit price (price_bps)
• Maker orders (resting on book): 0% fee
• Taker orders: 0.5% fee
• Time-in-force: GTC (default), IOC (Immediate-Or-Cancel), FOK (Fill-Or-Kill)
• May partially fill depending on available liquidity

When to Use Which

Complete Workflow Example

Real agent workflow: discover → analyze → quote → trade → monitor → redeem.

import json
import os
from langchain_flipcoin import FlipCoinToolkit

toolkit = FlipCoinToolkit(api_key=os.environ["FLIPCOIN_API_KEY"])
tools = toolkit.get_tools()

# Helper: find tool by name
def tool(name: str):
    return next(t for t in tools if t.name == name)

# 1. Check vault balance first
balance = json.loads(tool("flipcoin_get_vault_balance").invoke({}))
print(f"Vault: {int(balance['vaultBalance']) / 1e6:.2f} USDC")

# 2. Find trending open markets
markets = json.loads(tool("flipcoin_get_markets").invoke({
    "status": "open",
    "sort": "trending",
    "limit": 5,
}))
market = markets["markets"][0]
condition_id = market["conditionId"]
address = market["marketAddr"]
print(f"Market: {market['title']}")

# 2b. Get detailed market info (includes live prices)
details = json.loads(tool("flipcoin_get_market_details").invoke({
    "address": address,
}))
price_yes = details["market"]["currentPriceYesBps"]
print(f"YES: {price_yes / 100:.0f}%")

# 3. Get a quote before trading
quote = json.loads(tool("flipcoin_get_quote").invoke({
    "condition_id": condition_id,
    "side": "yes",
    "action": "buy",
    "amount": "5.0",
}))
if "error" in quote:
    print(f"Quote failed: {quote['error']}")
else:
    print(f"Shares: {int(quote['lmsr']['sharesOut']) / 1e6:.2f}")
    print(f"Price impact: {quote['lmsr']['priceImpactBps']} bps")

    # 4. Execute the trade
    trade = json.loads(tool("flipcoin_trade").invoke({
        "condition_id": condition_id,
        "side": "yes",
        "usdc_amount": "5.0",
    }))
    if "error" in trade:
        print(f"Trade failed: {trade['error']}")
    else:
        print(f"Trade confirmed: {trade['txHash']}")

# 5. Check portfolio after trading
portfolio = json.loads(tool("flipcoin_get_portfolio").invoke({"status": "open"}))
for pos in portfolio.get("positions", []):
    print(f"  {pos['title']}: {pos['netSide']} {pos['netShares']} shares, P&L: ${pos['pnlUsdc']}")

# 6. Redeem resolved positions
resolved = json.loads(tool("flipcoin_get_portfolio").invoke({"status": "resolved"}))
for pos in resolved.get("positions", []):
    payout = json.loads(tool("flipcoin_redeem_positions").invoke({
        "condition_id": pos.get("conditionId", ""),
    }))
    print(f"Redeemed: {payout}")

Agent Design Patterns

Best practices for building reliable trading agents:

1. Always check balance first — call flipcoin_get_vault_balance at the start of each session
2. Quote before trade — call flipcoin_get_quote before flipcoin_trade to preview price impact and fees
3. Store condition_id — after discovering a market, save its conditionId for subsequent operations (quote, trade, redeem)
4. Handle errors gracefully — all tools return JSON, check for "error" key before proceeding
5. Respect rate limits — avoid calling tools in tight loops (see Rate Limits below)
6. Use the right venue — let flipcoin_get_quote recommend the venue, or use CLOB for limit orders
7. Resolution workflow — propose_resolution → wait 24h → finalize_resolution (cannot skip dispute period)

Error Handling

All tools return JSON strings — they never raise exceptions to the LLM. On failure, the response contains an "error" key with a human-readable message that includes the error code:

result = json.loads(trade_tool.invoke({...}))
if "error" in result:
    error_msg = result["error"]
    # Error codes are prefixed: "INSUFFICIENT_BALANCE: vault balance too low"
    if "INSUFFICIENT_BALANCE" in error_msg:
        # Deposit more funds
        ...
    elif "RATE_LIMITED" in error_msg:
        # Back off and retry
        ...

Common Error Codes

Rate Limits

The Agent API enforces rate limits per API key. Response headers include X-RateLimit-Remaining and Retry-After (on 429).

Note: flipcoin_get_quote calls the public quote endpoint which is IP-rate-limited (not counted against your API key quota). propose_resolution and finalize_resolution use the relay class (30 req/hr).

For autonomous agents, implement exponential backoff when you encounter RATE_LIMITED errors.

Using a Pre-built Client

If you need custom configuration, you can pass a pre-built flipcoin SDK client:

from flipcoin import FlipCoin
from langchain_flipcoin import FlipCoinToolkit

client = FlipCoin(api_key="fc_...", base_url="https://www.flipcoin.fun")
toolkit = FlipCoinToolkit(client=client)
tools = toolkit.get_tools()

Note: The flipcoin package (PyPI: flipcoin) is the low-level HTTP SDK. langchain-flipcoin wraps it as LangChain tools with input validation, USDC conversion, and error handling.

Using Individual Tools

from flipcoin import FlipCoin
from langchain_flipcoin import FlipCoinGetMarkets, FlipCoinTrade

client = FlipCoin(api_key="fc_...")

# Use tools individually
markets_tool = FlipCoinGetMarkets(client=client)
result = markets_tool.invoke({"status": "open", "sort": "trending"})

trade_tool = FlipCoinTrade(client=client)
result = trade_tool.invoke({
    "condition_id": "0x...",
    "side": "yes",
    "usdc_amount": "5.0",
})

Examples

See the examples/ directory:

• langchain_agent.py — Complete LangChain ReAct agent with system prompt, tool loading, and conversation loop

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=langchain_flipcoin

Links

• FlipCoin Platform — Main app
• Agent API Documentation — Full API reference
• FlipCoin Python SDK — Low-level HTTP client (flipcoin)

License

MIT