LiberFi Prediction Market

Browse prediction market events, manage positions, and place orders on Kalshi and Polymarket using the LiberFi CLI.

Pre-flight Checks

See bootstrap.md for CLI installation and connectivity verification.

This skill's auth requirements:

Recommended flow (TEE auto): polymarket-setup → polymarket-place / kalshi-place / cancel. The server holds the user's TEE wallet via Privy and signs every transaction internally — no POLY_* HMAC, no Solana signing, no EIP-712 work for the caller.

Legacy flow: Polymarket order operations via polymarket-order require CLOB HMAC authentication via five --poly-* flags. These are NOT LiberFi JWT credentials — they are the user's own Polymarket CLOB API credentials.

TEE Auto Order Flow (CRITICAL)

For the canonical end-to-end order placement flow — including pre-flight status checks, deposit handling, market vs limit order branching, and post- order verification — see reference/order-flow.md.

The CLI/skill expects this exact ordering for Polymarket:

1. lfi status — confirm authenticated; if not, run lfi login key
2. lfi predict polymarket-setup-status --json — check Safe deployment +

token approvals

1. If safe_deployed=false or any approval missing: `lfi predict

polymarket-setup --json` (one-shot; gasless via Builder Relayer)

1. Check Safe USDC balance — pass the TEE EOA, NOT the Safe:

lfi predict balance --source polymarket --user <tee-eoa> --json (server derives Safe from EOA internally). If balance < 2, fetch BRIDGE deposit addresses using the Safe address from step 2/3: lfi predict polymarket-deposit-addresses --safe-address <safe> --json → returns { evm, svm, btc, tron }. Pick the field matching the user's chain (default evm for ETH/Polygon/Base/Arb/Op/BNB). Tell user to send ≥ $2 USDC to that bridge address (NEVER to the Safe address — the Safe is Polymarket's internal custody contract, not a user-facing deposit target). The Polymarket Bridge service auto-credits the Safe.

1. Ask the user: market or limit? For limit, also ask price + size + GTC

vs GTD (with expiration if GTD). For market, ask USDC spend (BUY) or share count (SELL)

1. Show the final order summary, wait for explicit confirmation
2. `lfi predict polymarket-place --token-id <id> --side <s> --order-type

<t> [--price <p>] [--size <sz>] [--expiration <epoch>] --json`

1. lfi predict orders --source polymarket --json — verify open orders
2. lfi predict cancel <id> --source polymarket --json — cancel if user

asks

For Kalshi the flow is shorter: lfi predict kalshi-place --input-mint <inMint> --output-mint <outMint> --amount <amt> --json — quote, sign (SignSOL), and submit are all done server-side.

Skill Routing

CLI Command Index

Query Commands (read-only)

TEE Auto Flow Commands (recommended)

Legacy / Deprecated Commands

Parameter Reference

Events list (lfi predict events):

• --limit <n> — Max results per page
• --cursor <cursor> — Pagination cursor
• --status <status> — Event status filter (e.g. active, resolved)
• --source <source> — Provider source: kalshi or polymarket
• --tag-slug <slug> — Filter by tag
• --search <query> — Free-text search
• --sort-by <field> — Sort field
• --sort-asc <bool> — Sort ascending: true or false
• --with-markets <bool> — Include embedded markets: true or false

Event detail (lfi predict event <slug>):

• <slug> — Required. Event slug identifier
• --source <source> — Required. Provider source: kalshi or polymarket

Balance (lfi predict balance):

• --source <source> — Required. Provider source: kalshi or polymarket
• --user <address> — Required. For polymarket: pass the user's TEE EOA (e.g. evmAddress from lfi whoami); the server auto-derives the Safe via CREATE2. NEVER pass a Safe address here. For kalshi: pass the Solana public key (solAddress).

Positions (lfi predict positions):

• --user <address> — Required. Same rule as balance: TEE EOA for polymarket (server derives Safe), Solana public key for kalshi.
• --source <source> — Optional provider source filter

Trades (lfi predict trades):

• --wallet <address> — Required. Same rule as balance: TEE EOA for polymarket (server derives Safe), Solana public key for kalshi.
• --source <source> — Optional provider source filter
• --limit <n> — Max results per page
• --cursor <cursor> — Pagination cursor
• --type <types> — Comma-separated trade types
• --side <side> — Trade side filter

Orders (lfi predict orders):

• --source <source> — Provider source
• --wallet-address <address> — Wallet address (required for kalshi)
• --market-id <id> — Market ID filter
• --asset-id <id> — Asset ID filter
• --next-cursor <cursor> — Pagination cursor
• --poly-api-key, --poly-address, --poly-signature, --poly-passphrase, --poly-timestamp — Polymarket CLOB auth (required when source is polymarket)

Order detail (lfi predict order <id>):

• <id> — Required. Order ID
• --source <source> — Required. Provider source
• Same --poly-* flags as orders list

Polymarket tick size (lfi predict polymarket-tick-size):

• --token-id <id> — Required. Polymarket CLOB token ID

Polymarket fee rate (lfi predict polymarket-fee-rate):

• --token-id <id> — Required. Polymarket CLOB token ID

Polymarket setup status (lfi predict polymarket-setup-status):

• --wallet-address <addr> — Optional EVM address. Defaults to caller's TEE wallet when authenticated.

Polymarket setup (run) (lfi predict polymarket-setup):

• No flags. Requires authentication. Idempotent — safe to call repeatedly.

Polymarket deposit addresses (lfi predict polymarket-deposit-addresses):

• --safe-address <addr> — Required. Safe wallet address (from polymarket-setup-status)

Polymarket place (TEE auto) (lfi predict polymarket-place):

• --token-id <id> — Required. Polymarket CLOB token ID
• --side BUY|SELL — Required.
• --order-type GTC|GTD|FOK|FAK|MARKET — Required.
• --price <p> — Limit price (limit orders only, e.g. 0.55). Required for GTC/GTD/FOK/FAK.
• --size <sz> — Limit: shares; market BUY: USDC; market SELL: shares. Required for limit and market.
• --expiration <epochSec> — Required for GTD.
• --neg-risk true|false — Force NegRisk exchange. Auto-detected when omitted.
• --fee-rate-bps <n> — Override fee rate (PS auto-resolves when omitted).
• --tick-size <n> — Override tick size (PS auto-resolves when omitted).
• --taker-address <addr> — Restrict the taker (advanced).

Kalshi place (TEE auto) (lfi predict kalshi-place):

• --input-mint <addr> — Required. Input token mint
• --output-mint <addr> — Required. Output token mint
• --amount <amt> — Required. Amount in smallest unit
• --slippage-bps <bps> — Slippage tolerance in basis points

Cancel order (lfi predict cancel <id>):

• <id> — Required. Order ID
• --source polymarket|kalshi — Required. For polymarket the L2 HMAC headers are derived from the caller's TEE wallet automatically.

Kalshi quote (lfi predict kalshi-quote):

• --input-mint <address> — Required. Input token mint address
• --output-mint <address> — Required. Output token mint address
• --amount <amount> — Required. Swap amount
• --user-public-key <key> — Required. User's Solana public key
• --slippage-bps <bps> — Slippage tolerance in basis points

Kalshi submit (lfi predict kalshi-submit):

• --signed-transaction <tx> — Required. Signed transaction data
• --order-context <json> — Required. Order context as JSON string (contains user_public_key, market_slug, side, outcome, mints, amount, price, slippage_bps)

Polymarket order (lfi predict polymarket-order):

• --body <json> — Required. Raw order JSON string
• --poly-api-key <key> — Required. Polymarket API key
• --poly-address <address> — Required. Polymarket address
• --poly-signature <sig> — Required. Polymarket HMAC signature
• --poly-passphrase <pass> — Required. Polymarket passphrase
• --poly-timestamp <ts> — Required. Polymarket timestamp

Operation Flow

Browse Prediction Events

1. Fetch events: lfi predict events --with-markets true --limit 20 --json
2. Present results: Show event title, status, number of markets, volume
3. Suggest next step: "Want to see details for a specific event?" / "需要查看某个事件的详情？"

Browse Events by Source

1. Determine source: Ask user for kalshi or polymarket
2. Fetch: lfi predict events --source kalshi --with-markets true --limit 20 --json
3. Present: Events filtered by provider
4. Suggest next step: "Pick an event to view its markets and outcomes"

View Event Details

1. Determine slug: From user selection or input
2. Fetch event: lfi predict event <slug> --source <source> --json
3. Present: Event title, description, status, resolution sources, markets with outcomes and prices
4. Suggest next step: "Want to check your balance or place an order?"

Check USDC Balance

If the user says "我的余额", "my balance", "我在 Polymarket/Kalshi 有多少钱" or any first-person variant — DO NOT ask for a wallet address. Use the "My ..." auto-flow below.

Generic flow (when the user explicitly provides someone else's address):

1. Collect inputs: Source (kalshi/polymarket) and wallet address
2. Fetch: lfi predict balance --source <source> --user <address> --json
3. Present: Available USDC balance
4. Suggest next step: "Ready to place a prediction?" / "准备下注了吗？"

Kalshi Order Flow (Quote → Sign → Submit)

1. Browse events: lfi predict events --source kalshi --with-markets true --json
2. View event: lfi predict event <slug> --source kalshi --json — identify market, outcomes, and mints
3. Check balance: lfi predict balance --source kalshi --user <publicKey> --json
4. Get quote: lfi predict kalshi-quote --input-mint <inMint> --output-mint <outMint> --amount <amt> --user-public-key <key> --json
5. Present quote: Show expected output amount, price, slippage
6. (mandatory) Wait for explicit user confirmation
7. User signs the transaction (externally, e.g. via wallet)
8. Submit: lfi predict kalshi-submit --signed-transaction <signedTx> --order-context '<contextJson>' --json
9. Present result: Show signature, status

Polymarket Order Flow

1. Browse events: lfi predict events --source polymarket --with-markets true --json
2. View event: lfi predict event <slug> --source polymarket --json
3. Check balance: lfi predict balance --source polymarket --user <address> --json
4. Prepare order body: Construct the Polymarket order JSON
5. (mandatory) Show order summary and wait for explicit user confirmation
6. Create order: lfi predict polymarket-order --body '<orderJson>' --poly-api-key <key> --poly-address <addr> --poly-signature <sig> --poly-passphrase <pass> --poly-timestamp <ts> --json
7. Present result: Show order response

View Positions

If the user says "我的持仓", "我现在押了哪些", "my positions", "我赌了什么" or any first-person variant — DO NOT ask for a wallet address. Use the "My ..." auto-flow below.

Generic flow (when the user explicitly provides someone else's address):

1. Determine user: Get wallet address from user
2. Fetch: lfi predict positions --user <address> --json
3. Present: Show event/market, outcome, size, entry price, current value
4. Suggest next step: "Want to see your trade history?" / "需要查看交易历史？"

View Trade History

If the user says "我的交易", "我赚了多少", "我亏了多少", "my trades", "我的盈亏" or any first-person variant — DO NOT ask for a wallet address. Use the "My ..." auto-flow below.

Generic flow (when the user explicitly provides someone else's address):

1. Determine wallet: Get wallet address from user
2. Fetch: lfi predict trades --wallet <address> --limit 20 --json
3. Present: Show trade timestamp, event/market, side, price, size
4. Suggest next step: "Want to check your current positions?" / "需要查看当前持仓？"

"My ..." auto-flow (CRITICAL — covers "我的", "my", "我自己")

Whenever the user asks about THEIR OWN prediction-market data — positions, trades, balance, PnL, "我现在押了哪些", "我在预测市场赚了多少", "我在 Polymarket 上的钱", etc. — run this exact sequence. NEVER ask the user to type their wallet address.

1. Check session: lfi status --json
2. If not authenticated (or expired: true):

lfi login key --role AGENT --name "OpenClawAgent" --json

1. Fetch TEE wallet addresses: lfi whoami --json

→ returns evmAddress (use for Polymarket) and solAddress (use for Kalshi).

1. Determine source(s):

• If the user named "Polymarket" → use evmAddress only.
• If the user named "Kalshi" → use solAddress only.
• If neither was named (e.g. "我在预测市场赚了多少") → query BOTH and merge.

1. Run the matching query for each source — pass the TEE EOA / SOL pubkey

from step 3 DIRECTLY. NEVER convert to a Safe address first; the server does that internally for Polymarket.

• Positions: lfi predict positions --user <evmAddress|solAddress> [--source <s>] --json
• Trades: lfi predict trades --wallet <evmAddress|solAddress> [--source <s>] --limit 50 --json
• Balance: lfi predict balance --source <s> --user <evmAddress|solAddress> --json

1. Present a single consolidated answer that names the source(s) used and,

for the "我赚了多少" / PnL question, sums realized + unrealized PnL across the returned trades/positions.

Why this is mandatory: prediction queries always require an address parameter in the CLI, but a normal user does NOT know their TEE wallet address — the LiberFi server holds it. The skill must resolve "我" → TEE wallet via whoami, transparently. The user should never have to type or even see the hex/Base58 address unless they ask.

EOA vs Safe — critical distinction for Polymarket: The address from whoami.evmAddress is the user's TEE EOA. For balance / positions / trades queries, ALWAYS pass the EOA — the prediction-server derives the Polymarket Safe via CREATE2 internally. The Safe address (returned by polymarket-setup-status) is ONLY for polymarket-deposit-addresses --safe-address (Polymarket Bridge requires the actual Safe as bridge key). Mixing these up → balance / positions / trades return EMPTY because the server tries to derive a Safe from an already-Safe address.

Check Order Status

1. List orders: lfi predict orders --source <source> --wallet-address <address> --json
2. Or get specific order: lfi predict order <id> --source <source> --json
3. Present: Show order status, side, price, filled amount

Cross-Skill Workflows

"Research an event and place a bet"

Full flow: predict → predict → predict → predict → predict

1. predict → lfi predict events --search "bitcoin" --with-markets true --json
2. predict → lfi predict event <slug> --source kalshi --json — view markets and outcomes
3. predict → lfi predict balance --source kalshi --user <publicKey> --json — check funds
4. predict → lfi predict kalshi-quote --input-mint <in> --output-mint <out> --amount <amt> --user-public-key <key> --json — get quote
5. Present quote, wait for confirmation, user signs transaction
6. predict → lfi predict kalshi-submit --signed-transaction <tx> --order-context '<ctx>' --json

"Check my prediction portfolio and trade history"

Full flow: predict → predict

1. predict → lfi predict positions --user <address> --json — current positions
2. predict → lfi predict trades --wallet <address> --limit 50 --json — trade history
3. Present consolidated portfolio view

"Browse events, then research the underlying token"

Full flow: predict → token → token

1. predict → lfi predict events --with-markets true --limit 10 --json
2. User selects an event related to a specific token
3. token → lfi token info sol <tokenAddress> --json — token details
4. token → lfi token security sol <tokenAddress> --json — security audit

Suggest Next Steps

Edge Cases

• Invalid source: If the API returns an error about source, list valid sources (kalshi, polymarket) and ask the user to choose
• No events found: Inform user: "No prediction events found matching your criteria. Try different filters or search terms."
• Empty positions: Inform user: "No open positions found for this wallet. You can browse events to find prediction opportunities."
• Insufficient balance: If balance is too low for a trade, inform the user and suggest depositing funds
• Invalid slug: If event not found, suggest searching events first via lfi predict events --search <keyword>
• Polymarket auth missing: If POLY_* flags are missing for Polymarket operations, list all required flags and ask the user to provide them
• Invalid JSON in --body or --order-context: If JSON parsing fails, show the parse error and ask the user to correct the JSON
• Quote expired: Kalshi quotes have limited validity; if too much time passes, get a new quote
• Network timeout: Retry once after 3 seconds; if still fails, suggest checking connectivity via lfi ping --json

Common Pitfalls

Security Notes

See security-policy.md for global security rules.

Skill-specific rules:

• Polymarket CLOB credentials are sensitive — never log, display, or store POLY_* values beyond the immediate command execution
• Kalshi transactions involve real funds — never fabricate or guess signed transaction data
• NEVER place orders without explicit user confirmation — always show the order summary first
• The --order-context and --body fields are opaque — pass them through as-is; do not interpret, modify, or display raw content beyond summarizing key fields (amount, side, market)
• After order submission, provide the result so the user can independently verify