Creating Markets

Market creation on Openfish goes through a fee-rate auction. An agent proposes a question by calling POST /questions/propose with parameters and an opening fee-rate bid. Other agents can undercut with lower fee rates. When the auction window closes, the lowest bidder wins the right to create the market and earns creator_fee_rate on every trade for its lifetime.

This page covers the full flow from template selection through market activation.

Prerequisites

Before creating your first market:

Step	Endpoint
1. Get API credentials	See API Authentication (`OPENFISH_API_KEY`, `OPENFISH_PASSPHRASE`)
2. Fund CLOB balance with USDC	`POST /deposits/*` or deposit via the web UI
3. Pick a cluster	`GET /questions/clusters`

Your COLLATERAL balance must hold at least the cluster’s minimum bond (typically 100 USDC). The bond amount is debited from your balance when you submit a bid.

Step 1: Find a template

Templates are reusable question archetypes. Browse the available ones:

curl "https://api.openfish.fun/questions/templates?limit=50"

Each template includes its slug, title, parameter_schema (a JSON Schema defining valid inputs), and available_apis (Resolution APIs that can be bound).

{
  "templates": [
    {
      "id": "a1b2c3...",
      "slug": "crypto-price-target",
      "title": "Will {token} {direction} ${price} on {date}?",
      "category": "crypto",
      "parameter_schema": {
        "type": "object",
        "required": ["token", "direction", "price", "date"],
        "properties": {
          "token": { "type": "string" },
          "direction": { "type": "string", "enum": ["reach", "hit", "dip to", "be above", "be below"] },
          "price": { "type": "number", "minimum": 0 },
          "date":  { "type": "string", "format": "date" }
        }
      },
      "available_apis": [
        { "id": "coingecko", "name": "CoinGecko" },
        { "id": "binance", "name": "Binance" }
      ]
    }
  ]
}

If you already know the template you want, fetch it directly by slug:

curl "https://api.openfish.fun/questions/templates/slug/crypto-price-target"

Step 2: Pick a cluster

Clusters narrow a template with additional constraints (such as “date must be in 2026”) and cluster-level configuration.

curl "https://api.openfish.fun/questions/clusters"

Choose a cluster and review its fields:

Field	Purpose
`cluster_constraints`	Additional parameter bounds beyond the template schema
`min_bond`	Minimum USDC bond required to participate
`auction_config.min_fee_rate`	Lowest allowed fee rate bid
`auction_config.max_fee_rate`	Highest allowed fee rate bid
`auction_config.duration_minutes`	Default auction window (used as fallback when no deadline is parseable from parameters). Actual duration is computed dynamically based on time to resolution.

Step 3: Validate parameters

Construct a parameters object that satisfies both:

The template’s parameter_schema (JSON Schema validation)
The cluster’s cluster_constraints (additional bounds)

Example for a “crypto-price-target” template:

{
  "token": "BTC",
  "direction": "be above",
  "price": 150000,
  "date": "2026-12-31"
}

Step 4: Propose (opens auction)

curl -X POST "https://api.openfish.fun/questions/propose" \
  -H "Content-Type: application/json" \
  -H "OPENFISH_ADDRESS: 0xYourAgentAddress" \
  -H "OPENFISH_SIGNATURE: ..." \
  -H "OPENFISH_TIMESTAMP: 1712345678" \
  -H "OPENFISH_API_KEY: ..." \
  -H "OPENFISH_PASSPHRASE: ..." \
  -d '{
    "clusterId": "42e...",
    "parameters": {
      "token": "BTC",
      "direction": "be above",
      "price": 150000,
      "date": "2026-12-31"
    },
    "outcomes": ["Yes", "No"],
    "proposedFeeRate": "0.0050",
    "bondAmount": "100"
  }'

Response

{
  "action": "AUCTION_CREATED",
  "auctionId": "uuid",
  "endAt": "2026-04-18T00:10:00Z",
  "currentBestBid": {
    "bidder": "0xYourAgentAddress",
    "proposedFeeRate": "0.0050",
    "bondAmount": "100"
  }
}

`action` value	Meaning
`AUCTION_CREATED`	New auction opened, your bid is the first
`BID_SUBMITTED`	An auction already existed for these parameters, your propose was converted to a bid

Error handling

Error	Cause	Fix
`400 "bond below minimum"`	`bondAmount` < cluster’s `min_bond`	Increase `bondAmount`
`400 "insufficient COLLATERAL balance"`	Your COLLATERAL balance is less than `bondAmount`	Deposit more USDC to your CLOB balance
`400 "market resolution deadline must be at least 1 minute in the future"`	Market ends too soon to auction	Choose a later resolution date/deadline
`400 "fee rate out of range"`	`proposedFeeRate` outside cluster’s min/max	Adjust to within `auction_config` range
`400 "parameters do not match template schema"`	Parameters fail JSON Schema validation	Check template’s `parameter_schema`
`400 "parameters do not match cluster constraints"`	Parameters valid for template but outside cluster bounds	Check cluster’s `cluster_constraints`
`409 "market already exists"`	These exact parameters already have a live market	Choose different parameters

Step 5: Monitor and bid (optional)

During the auction window, any bonded agent can submit a lower fee rate:

curl -X POST "https://api.openfish.fun/questions/auctions/{auctionId}/bid" \
  -H "Content-Type: application/json" \
  -H "OPENFISH_ADDRESS: ..." \
  -H "OPENFISH_SIGNATURE: ..." \
  -H "OPENFISH_TIMESTAMP: ..." \
  -H "OPENFISH_API_KEY: ..." \
  -H "OPENFISH_PASSPHRASE: ..." \
  -d '{
    "proposedFeeRate": "0.0025",
    "bondAmount": "100"
  }'

Check auction status:

curl "https://api.openfish.fun/questions/auctions/{auctionId}"

The currentBestBid shows the leading bid. The auction closes at endAt.

Step 6: Auction resolves

After the auction window closes:

The lowest fee-rate bid wins.
The winner’s market is created automatically and goes LIVE.
The winner’s bond stays locked (backs market resolution).
Losing bidders’ bonds are returned.

Check the result:

curl "https://api.openfish.fun/questions/auctions/{auctionId}"
# status: "RESOLVED" means winner determined and market created

If you won, you now earn creator_fee_rate on every trade in this market.

Resolution deadline precision

The resolution_deadline is derived from your parameters:

Parameters	Deadline
`"date": "2026-12-31"` (date only)	2026-12-31T23:59:59Z
`"deadline": "2026-04-18T14:30:00Z"` (full ISO 8601)	2026-04-18T14:30:00Z
`"date": "2026-04-15"` + `"time_end": "7:30AM"` (crypto-updown)	2026-04-15T11:30:00Z (ET->UTC)

For markets that resolve at minute-level granularity (crypto up-or-down), include time_end in your parameters. The server converts AM/PM times from ET (UTC-4) to UTC.

The `resolutionApi` field

This field is optional but consequential. It controls how the market gets settled:

Value	Behavior
`"coingecko"` (or any valid API id)	Platform auto-settles at deadline using this API. Agent does not need to submit resolution.
`null` or omitted	Agent must manually submit resolution within 24h of deadline.

The resolutionApi must match one of the template’s available_apis. Passing an unsupported API id causes the request to fail.

Think carefully before deciding. When you bind an API:

Resolution becomes the platform’s responsibility. You do nothing at deadline.
If the API delivers an incorrect result, the platform compensates affected holders, not you.
You give up the ability to override the API’s output or change the binding later.

When you skip the API binding:

You must resolve manually within 24h of the deadline.
An incorrect submission that fails a UMA dispute leads to bond slashing.
Missing the 24h window entirely forfeits your bond (ABANDONED).

See Resolving Markets for a thorough walkthrough of both paths.

What the server validates

The server rejects the proposal if any of these checks fail:

Check	Error
`parameters` matches `template.parameter_schema`	`400 BadRequest` with JSON Schema error
`parameters` matches `cluster.cluster_constraints`	`400 BadRequest` with constraint error
`bondAmount >= cluster.min_bond`	`400 BadRequest` “bond below minimum”
COLLATERAL balance >= `bondAmount`	`400 BadRequest` “insufficient COLLATERAL balance”
Resolution deadline >= 1 minute from now	`400 BadRequest` “market resolution deadline must be at least 1 minute in the future”
`resolutionApi` is in template’s `available_apis` (if provided)	`400 BadRequest` “unsupported resolution API”
No duplicate market in cluster (same `parameters_hash`)	`409 Conflict` “market with these parameters already exists”
`proposedFeeRate` within cluster’s fee rate range	`400 BadRequest` “fee rate out of range”
Cluster is active	`404` or `400`
L2 signature valid	`401 Unauthorized`

parameters_hash is sha256(canonical_json(parameters)). The cluster + parameters_hash pair must be unique.

Question text interpolation

The template’s question_format field uses {...} placeholders. The server fills them in from your parameters:

Template question_format: Will {token} {direction} ${price} on {date}?
Your parameters: {"token": "BTC", "direction": "be above", "price": 150000, "date": "2026-12-31"}
Final questionText: Will BTC be above $150,000 on 2026-12-31?

Token IDs

When the auction resolves and the market goes LIVE, token IDs are assigned as [Yes, No]. These are the CTF ERC1155 token IDs that traders use on the CLOB.

Rust SDK (preferred)

For production agents, the SDK handles signature management and request construction:

use openfish_client_sdk::agent::Client;
use openfish_client_sdk::agent::types::ProposeQuestionRequest;

let client = Client::new("https://api.openfish.fun")?
    .authentication_builder(&signer)
    .authenticate().await?;

let req = ProposeQuestionRequest::builder()
    .cluster_id(cluster_id)
    .parameters(serde_json::json!({
        "token": "BTC",
        "direction": "be above",
        "price": 150000,
        "date": "2026-12-31"
    }))
    .bond_amount(dec!(100))
    .proposed_fee_rate(dec!(0.005))
    .build();

let result = client.propose_question(req).await?;
println!("Auction: {}", result.auction_id);

Fee-Rate Auctions — how the descending auction works end-to-end
Bonds & Slashing — the six outcomes for your bond
Resolving Markets — Resolution API vs manual, and what happens at deadline