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 --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 --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 --side --order-type

[--price

] [--size ] [--expiration ] --json`

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

asks

For Kalshi the flow is shorter: `lfi predict kalshi-place --input-mint

--output-mint --amount --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 — Max results per page
• --cursor — Pagination cursor
• --status — Event status filter (e.g. active, resolved)
• --source — Provider source: kalshi or polymarket
• --tag-slug — Filter by tag
• --search — Free-text search
• --sort-by — Sort field
• --sort-asc — Sort ascending: true or false
• --with-markets — Include embedded markets: true or false

Event detail (lfi predict event ):

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

Balance (lfi predict balance):

• --source — Required. Provider source: kalshi or polymarket
• --user
  — 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
  — Required. Same rule as balance: TEE EOA for polymarket (server derives Safe), Solana public key for kalshi.
• --source — Optional provider source filter

Trades (lfi predict trades):

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

Orders (lfi predict orders):

• --source — Provider source
• --wallet-address
  — Wallet address (required for kalshi)
• --market-id — Market ID filter
• --asset-id — Asset ID filter
• --next-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 ):

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

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

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

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

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

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

• --wallet-address — 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 — Required. Safe wallet address (from polymarket-setup-status)

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

• --token-id — Required. Polymarket CLOB token ID
• --side BUY|SELL — Required.
• --order-type GTC|GTD|FOK|FAK|MARKET — Required.
• --price

  — Limit price (limit orders only, e.g. 0.55). Required for GTC/GTD/FOK/FAK.

• --size — Limit: shares; market BUY: USDC; market SELL: shares. Required for limit and market.
• --expiration — Required for GTD.
• --neg-risk true|false — Force NegRisk exchange. Auto-detected when omitted.
• --fee-rate-bps — Override fee rate (PS auto-resolves when omitted).
• --tick-size — Override tick size (PS auto-resolves when omitted).
• --taker-address — Restrict the taker (advanced).

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

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

Cancel order (lfi predict cancel ):

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

Kalshi submit (lfi predict kalshi-submit):

• --signed-transaction — Required. Signed transaction data
• --order-context — 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 — Required. Raw order JSON string
• --poly-api-key — Required. Polymarket API key
• --poly-address
  — Required. Polymarket address
• --poly-signature — Required. Polymarket HMAC signature
• --poly-passphrase — Required. Polymarket passphrase
• --poly-timestamp — 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 --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 --user
   --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 --source kalshi --json — identify market, outcomes, and mints
3. Check balance: lfi predict balance --source kalshi --user --json
4. Get quote: lfi predict kalshi-quote --input-mint --output-mint --amount --user-public-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 --order-context '' --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 --source polymarket --json
3. Check balance: lfi predict balance --source polymarket --user
   --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 '' --poly-api-key --poly-address --poly-signature --poly-passphrase --poly-timestamp --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
   --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
   --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.
2. 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 [--source ] --json
• Trades: lfi predict trades --wallet [--source ] --limit 50 --json
• Balance: lfi predict balance --source --user --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 --wallet-address
   --json
2. Or get specific order: lfi predict order --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 --source kalshi --json — view markets and outcomes
3. predict → lfi predict balance --source kalshi --user --json — check funds
4. predict → lfi predict kalshi-quote --input-mint --output-mint --amount --user-public-key --json — get quote
5. Present quote, wait for confirmation, user signs transaction
6. predict → lfi predict kalshi-submit --signed-transaction --order-context '' --json

"Check my prediction portfolio and trade history"

> Full flow: predict → predict

1. predict → lfi predict positions --user
   --json — current positions
2. predict → lfi predict trades --wallet
   --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 --json — token details
4. token → lfi token security sol --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
• 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