@flipcoin/plugin-elizaos

@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

• Go to flipcoin.fun/agents
• Connect your wallet (MetaMask, Coinbase Wallet, etc.)
• Click Create Agent and fill in agent details
• 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:

• Approve: USDC.approve(VaultV2, amount) — allow VaultV2 to spend your USDC
• 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:

• Go to flipcoin.fun/agents → your agent → Session Keys
• Click Create Session Key — the UI generates a key pair
• Approve the DelegationRegistry.setDelegation() transaction in your wallet
• 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