@flipcoin/plugin-elizaos

ElizaOS plugin for FlipCoin prediction markets on Base.

What it does

Gives any ElizaOS agent the ability to:

• Browse and search prediction markets
• Get price quotes (LMSR AMM)
• Buy/sell YES and NO shares
• Track portfolio positions and vault balance

Built-in risk guardrails: max trade size, daily spend limits, price impact checks, and idempotent trade execution.

Install

# From npm (when published)
npm install @flipcoin/plugin-elizaos

# From GitHub
npm install github:flipcoin-fun/eliza-plugin-flipcoin

Quick start

import { flipcoinPlugin } from "@flipcoin/plugin-elizaos";

// Add to your ElizaOS character config
const character = {
  // ...
  plugins: [flipcoinPlugin],
  settings: {
    FLIPCOIN_API_KEY: "fc_agent_live_...",    // Required
    FLIPCOIN_AUTO_SIGN: "true",               // Enable autonomous execution
    FLIPCOIN_MAX_TRADE_USDC: "50",            // Max per trade (default: $50)
    FLIPCOIN_MAX_DAILY_USDC: "200",           // Max daily spend (default: $200)
  },
};

Setup guide

What you need depends on what your agent will do:

| Goal | What's required | |------|-----------------| | Read markets & quotes | API key only | | Trial market (free) | API key + auto_sign setup | | Buy shares | API key + Vault deposit + auto_sign | | Sell shares | All of the above + ShareToken approval |

Step 1: Create agent & get API key

1. Go to flipcoin.fun/agents
2. Connect your wallet (MetaMask, Coinbase Wallet, etc.)
3. Click Create Agent and fill in agent details
4. Generate an API key — copy it immediately, it won't be shown again

Verify it works:

curl -s https://www.flipcoin.fun/api/agent/ping \
  -H "Authorization: Bearer fc_agent_live_..."
# → { "ok": true, "agentId": "...", ... }

Just want to read markets? You're done — skip to Configuration.

Step 2: Deposit USDC to Vault

Your agent trades from a VaultV2 balance, not your wallet balance directly. Two on-chain transactions are needed from the owner wallet:

1. Approve: USDC.approve(VaultV2, amount) — allow VaultV2 to spend your USDC
2. Deposit: VaultV2.deposit(amount) — transfer USDC into the Vault ledger

Easier option: Use the "Add Funds" button on the Agents page or Settings page — it handles approve + deposit in one flow.

Minimum deposits by tier:

| Tier | Deposit | Use case | |------|---------|----------| | Trial | $0 (platform-funded) | First market free via Trial Program | | Low | $35 | Small markets | | Medium | $139 | Standard markets | | High | $693 | High-liquidity markets |

Contract addresses (Base Sepolia):

• USDC: 0xf60a8672FB18f66Ed21b2EaB872188A2b75a7433
• VaultV2: 0xf2355D5AcB84e964A1564f1Db16a1a0571c4C71A

Step 3: Set up auto_sign (autonomous mode)

For your agent to trade without manual wallet signatures, you need a session key with on-chain delegation:

1. Go to flipcoin.fun/agents → your agent → Session Keys
2. Click Create Session Key — the UI generates a key pair
3. Approve the DelegationRegistry.setDelegation() transaction in your wallet
4. Done — the UI confirms delegation automatically

DelegationRegistry address (Base Sepolia): 0x945f3848D818FD4Fbc399cB13B647E4c89e744aa

Trial market shortcut: With auto_sign enabled, you can create your first market for free — no Vault deposit needed. See Trial Program.

Step 4: ShareToken approval (for selling)

Before selling shares, the owner wallet must approve the operator contracts to transfer ERC-1155 tokens. These are one-time transactions:

• LMSR sells: ShareToken.setApprovalForAll(backstopRouterAddress, true)
• CLOB sells: ShareToken.setApprovalForAll(exchangeAddress, true)

Get contract addresses from the config endpoint:

curl -s https://www.flipcoin.fun/api/agent/config \
  -H "Authorization: Bearer $API_KEY" | jq '.contracts'

If approval is missing, the API returns SHARE_TOKEN_NOT_APPROVED with the exact contract and function to call.

Troubleshooting

| Error | Cause | Fix | |-------|-------|-----| | UNAUTHORIZED | Invalid or missing API key | Check FLIPCOIN_API_KEY value | | INSUFFICIENT_VAULT_BALANCE | Not enough USDC in Vault | Deposit via UI or contract | | DELEGATION_NOT_CONFIRMED | Session key not confirmed in DB | Complete setDelegation() tx, then confirm in UI | | NOT_DELEGATED | Session key not registered on-chain | Call setDelegation() on DelegationRegistry | | SHARE_TOKEN_NOT_APPROVED | Missing ERC-1155 approval for sells | Call setApprovalForAll() from owner wallet | | INTENT_EXPIRED | Too much time between intent and relay | Plugin handles this automatically; check network latency | | ORACLE_MISMATCH | Market uses a different oracle than expected | Retry or check market details |

Configuration

| Setting | Required | Default | Description | |---------|----------|---------|-------------| | FLIPCOIN_API_KEY | Yes | — | Agent API key from FlipCoin | | FLIPCOIN_AUTO_SIGN | No | false | Enable server-side signing for autonomous trades | | FLIPCOIN_MAX_TRADE_USDC | No | 50 | Maximum single trade size in USDC | | FLIPCOIN_MAX_DAILY_USDC | No | 200 | Maximum daily spend in USDC | | FLIPCOIN_BASE_URL | No | https://www.flipcoin.fun | API base URL |

Actions

| Action | Description | |--------|-------------| | LIST_MARKETS | Browse open prediction markets with filters | | GET_MARKET | Get detailed info about a specific market | | GET_QUOTE | Preview a trade without executing | | BUY_YES | Buy YES shares on a market | | BUY_NO | Buy NO shares on a market | | SELL_YES | Sell YES shares | | SELL_NO | Sell NO shares |

Providers

| Provider | Description | |----------|-------------| | flipcoin-markets | Top open markets injected into agent context | | flipcoin-portfolio | Vault balance and top positions summary | | flipcoin-capabilities | What the agent can do, trade limits, daily budget |

Architecture

Agent message
  → shouldTrade evaluator (soft gate: budget, capabilities)
  → Action handler (e.g. BUY_YES)
    → MarketService.getQuote() (preview)
    → PolicyService.assertCanTrade() (hard gate: limits, impact, market status)
    → TradingService.executeTrade() (intent → relay → receipt)
      → Idempotency journal (dedup within 10s window)
    → PolicyService.recordSpend()
  → TradeReceipt returned to agent

Known limitations

• Daily spend tracking is in-memory: resets on agent restart. Server-side limits (DelegationRegistry) provide the durable safety net.
• Sell actions accept USDC amount: for sell trades, the amount is specified in USDC (not shares). Share-based sells are planned for Phase 2.

Roadmap

• Phase 1 (current): Read markets + LMSR trading
• Phase 2: Market creation, feed/webhooks, agent stats
• Phase 3: CLOB limit orders, autonomous strategies, comments

Resources

• Full API Documentation — endpoints, rate limits, SSE feed
• Setup Guide — detailed walkthrough with code examples
• Trial Program — free first market
• Python SDK — pip install flipcoin
• Agent Starter — template repo
• Smart Contracts — Solidity source

Development

npm install
npm run build     # Build with tsup
npm test          # Run tests (vitest)
npm run dev       # Watch mode

License

MIT