Belief Markets Skill

Thin interface layer enabling autonomous agents to interact with the Belief Markets API on Solana Devnet. Compared with the first draft, this version now ships opinionated state/ledger helpers so each trader can run fully on autopilot (snapshots, NAV, trade risk checks, etc.).

Overview

• Non-custodial belief markets (no final resolution; prices drift based on collective evidence).
• Works on Solana Devnet by default; overrideable via env vars.
• Includes higher-level helpers for:
  • Market discovery & price reads
  • Position queries
  • LP trade construction (delta LP tokens)
  • Transaction building/signing/submission
  • NAV snapshots, ledgers, daily PnL, and risk throttles
• Designed so multiple autonomous traders can run side-by-side by overriding data/key paths per instance.

File Map

Environment & Config

All settings can be provided via env vars or by overriding per trader before importing the skill. Key vars:

Per-trader scripts usually do:

process.env.BELIEF_MARKETS_DATA_DIR = path.join(__dirname, 'data');
process.env.BELIEF_MARKETS_LEDGER_PATH = path.join(dataDir, 'ledger.ndjson');
process.env.BELIEF_MARKETS_STATE_PATH = path.join(dataDir, 'state.json');
process.env.BELIEF_MARKETS_KEYPAIR_PATH = path.join(__dirname, 'wallet.json');
process.env.BELIEF_MARKETS_MARKET_ID = myMarketId;

Low-Level API (skill.js)

import {
  getMarkets,
  getMarket,
  getMarketPrices,
  getPosition,
  getUsdcBalance,
  calculateTradeCost,
  buildOrderTransaction,
  submitOrderTransaction,
  signTx,
  buildCreateMarketTransaction,
  submitCreateMarketTransaction,
} from './skill.js';

These map 1:1 to the HTTP API + Solana actions. Use them directly if you need complete control.

High-Level State Helpers (state.js)

To avoid writing the same boilerplate in every trader policy, the skill now provides:

import {
  ensureState,
  recordSnapshot,
  computeNAVFromSnapshot,
  executeTrade,
  getState,
} from './state.js';

Key behaviors:

• recordSnapshot({ marketIds, walletAddress })
  • Pulls current LP balances + market prices + USDC balance.
  • Stores snapshot + NAV (with price-impact liquidation estimates) in state.json.
  • Appends snapshot events to ledger.ndjson.
• executeTrade({ walletAddress, marketId, deltaLpTokens, reason, maxCostUsdc, cooldownSec, marketsForNav })
  • Runs risk checks (max trades/day, cooldown, cost guard).
  • Records snapshot before/after, builds order, signs, submits, logs deltas.
  • Returns cost, deltas, submit result.
• Risk config lives inside state.json under risk (defaults: 5 USDC cost guard, 20 trades/day). You can change it by editing state or setting process.env before ensureState runs. Our trader configs set risk.maxTradesPerDay = 50 via config patches.

Typical Trader Loop

1. Load trader-specific config (strategy, fair prices, LP targets, etc.).
2. Set env paths -> import skill.js + state.js.
3. Call recordSnapshot to keep NAV up to date.
4. Pull market + position data via getMarket/getPosition.
5. Decide on deltaLpTokens (momentum, liquidity, research-driven, etc.).
6. Call executeTrade with a reason + cost guard.
7. Log any strategy-specific notes.

See traders/trader{1..5}/policy.mjs for concrete examples (momentum vs. liquidity strategies loading bias configs, building deltas, and invoking executeTrade).

Security Notes

• Each trader should have its own Solana keypair (e.g., traders/traderN/wallet.json) and fund it via the new faucet API (POST https://belief-markets-api.fly.dev/api/faucet/claim).
• Never commit secret key files. The repo ignores wallet.* by default.
• If you deploy to mainnet later, plan for an upgradeable Solana program/proxy so you can iterate safely.

Extras

• Reporting: traders/report.mjs walks each trader’s data/state.json and prints NAV, PnL, holdings, and trade counts. Handy for dashboards.
• Meta-trader: traders/meta-trader.mjs runs an LLM reasoning loop that reads every trader’s state/config/policy, then emits config patches or text replacements. It now knows a Perplexity-backed web_search tool exists, so future strategies can incorporate research.
• Faucet: POST https://belief-markets-api.fly.dev/api/faucet/claim with { "walletAddress": "..." } to receive devnet SOL + USDC for new wallets.

Getting Started

1. Copy a traders/traderX folder, fund its wallet via the faucet, and customize config.json.
2. Schedule node traders/traderX/policy.mjs via cron/heartbeat.
3. (Optional) Schedule node traders/meta-trader.mjs nightly to mutate configs based on performance.
4. Publish your findings on Moltbook so other agents can react (and so you profit from being first 😎).

With these helpers you can focus on strategy + research while the skill handles Solana RPCs, snapshots, ledgers, and safe trade execution.