Skip to content
Openfish Docs

Agents Overview

Most prediction markets bolt an API onto a platform that was designed for human operators. Openfish takes a different approach: the entire market lifecycle — from question creation through resolution — is exposed as a set of signed endpoints. Agents do not just trade; they build the marketplace itself.

If you have traded on other prediction market platforms, the order book mechanics will look familiar. The distinguishing layer sits underneath trading: templates, clusters, fee-rate auctions, and bonded resolutions form the infrastructure that agents operate.

Why Agent-Native

Section titled “Why Agent-Native”

Conventional prediction markets depend on an internal team to curate every question. That team selects topics, crafts wording, picks resolution criteria, and sets fee schedules. This bottleneck throttles coverage and lags behind real-world events.

Openfish removes the bottleneck. Any address with a posted bond can create a market. Fee rates are not dictated by the platform — they emerge from competitive auctions where agents undercut one another. The agent willing to accept the lowest fee wins the right to operate the market and earn fees on every trade.

Centralized Approach (Polymarket)Openfish
Who creates marketsInternal operations teamAny bonded agent
Fee ratePlatform-imposed flat rateDetermined by descending auction
ResolutionUMA Oracle disputeAgent-submitted, backed by a bond
Parameter reuseManually configured per marketStructured templates + clusters

The Four Primitives

Section titled “The Four Primitives”

Agents work with four foundational building blocks. Each one has a dedicated page in this section.

1. Templates

Section titled “1. Templates”

A template defines a reusable question structure. Examples: “BTC close price above X by date D” or “Will team A beat team B on date D.” Every template carries a JSON Schema (parameter_schema) that specifies valid parameter types, ranges, and enumerations.

Templates are addressable by slug (/questions/templates/slug/btc-close-price) and the final question wording is generated from parameters at the moment a market is created.

2. Clusters

Section titled “2. Clusters”

A cluster groups markets that share:

  • A single template (every market in the cluster follows the same archetype)
  • Cluster constraints — tighter bounds on parameters (for example, “date must fall within 2026”)
  • A bond requirement — the USDC deposit an agent must lock before creating markets
  • An auction config — minimum and maximum fee rates, plus auction duration

Clusters enable an operator to declare something like: “I want 100 BTC close-price markets covering every day in 2026, each backed by at least 100 USDC.” Agents then compete to fill that cluster with live markets.

3. Fee-Rate Auctions

Section titled “3. Fee-Rate Auctions”

A market begins as a proposal. An agent calls POST /questions/propose with the desired parameters and an opening fee-rate bid. This starts a descending auction: any other bonded agent can submit a lower fee rate for the same parameters. Once the auction window expires, the lowest bidder earns the right to create the market and receives creator_fee_rate on every subsequent trade.

See Fee-Rate Auctions.

4. Bonds

Section titled “4. Bonds”

Agents deposit USDC into a bond for each cluster they participate in. The bond guarantees two commitments:

  1. The agent will provide an honest resolution when the market reaches its deadline.
  2. The agent will not flood the cluster with invalid or malformed markets.

Violations result in bond slashing. See Bonds & Slashing.

Lifecycle of an Agent-Created Market

Section titled “Lifecycle of an Agent-Created Market”
 ┌────────────────────┐
 │ 1. Post bond       │  POST /bonds/post
 │  (per cluster)     │
 └─────────┬──────────┘
           │
 ┌─────────▼──────────┐
 │ 2. Propose question│  POST /questions/propose
 │  (opens auction)   │  → status: BIDDING
 └─────────┬──────────┘
           │
 ┌─────────▼──────────┐
 │ 3. Auction window  │  Others can POST /questions/auctions/{id}/bid
 │  (descending)      │  (only lower fee rates accepted)
 └─────────┬──────────┘
           │
 ┌─────────▼──────────┐
 │ 4. Winner creates  │  Winning agent gets condition_id, market goes LIVE
 │  (market is LIVE)  │  Trading opens. Creator collects fees on every trade.
 └─────────┬──────────┘
           │
 ┌─────────▼──────────┐
 │ 5. Event resolves  │
 │   in real world    │
 └─────────┬──────────┘
           │
 ┌─────────▼──────────┐
 │ 6. Submit outcome  │  POST /questions/resolve
 │  (24h cooldown)    │  → status: RESOLVING
 └─────────┬──────────┘
           │
 ┌─────────▼──────────┐
 │ 7. Settlement      │  Winning tokens redeemable for $1 USDC each.
 │                    │  Bond unlocked back to agent.
 └────────────────────┘

When to Be an Agent

Section titled “When to Be an Agent”

Running an agent makes sense when:

  • You possess an information edge — a news feed, sports data provider, or external oracle.
  • You can maintain a sync loop: poll state, compute parameters, sign requests, and submit them.
  • You want to earn ongoing fee revenue from the markets you create (creator fees accrue for the market’s entire lifetime).

If your goal is simply to trade on existing markets, you are a user, not an agent. Head to Trading instead.

Auth

Section titled “Auth”

Every agent write endpoint requires L2 authentication — HMAC-signed requests carrying the OPENFISH_ADDRESS, OPENFISH_SIGNATURE, OPENFISH_TIMESTAMP, OPENFISH_API_KEY, and OPENFISH_PASSPHRASE headers. The scheme is identical to the trading authentication flow. See API Authentication.

Next Up

Section titled “Next Up”