Copy page

Prediction Markets

TypeScript SDK — Predictions: Combos

Create and query combo instruments — bundles of prediction market contracts traded as a single unit. All methods are on client.predictions.

Availability — Combo endpoints are not currently enabled in production. They are available in the sandbox environment for testing.

createCombo

POST /v1/prediction-markets/combos · Authenticated

Create a new combo instrument from 2–6 contract legs. Each leg specifies a contractId (decimal string of the numeric contract ID) and a requiredOutcome ("Yes" or "No" — capitalized). This is a POST mutation — never automatically retried. The request body is validated client-side.

Code
const result = await client.predictions.createCombo({
  legs: [
    { contractId: "101", requiredOutcome: "Yes" },
    { contractId: "202", requiredOutcome: "No" },
  ],
});

console.log(result.combo.id);               // bigint — internal combo ID
console.log(result.combo.instrumentSymbol);  // e.g. "GEMI-CMB-0526-A7F3B2C1D4E5"
console.log(result.combo.canonicalLegKey);   // e.g. "101:Yes|202:No"
console.log(result.alreadyExisted);          // true if canonical combo already existed

Validated fields per leg:

Field	Rule	Required
contractId	string only — the SDK validates it as a string, not a numeric value (passing a number will fail validation)	Yes
requiredOutcome	"Yes" or "No" (capitalized)	Yes

Validated — The legs array must contain 2–6 items. The SDK validates each leg locally and throws ValidationError on mismatch before making a network call. See Request Validation.

Tip — Response fields combo.id, combo.instrumentId, and combo.legs[*].comboId are bigint. See Data Types.

getComboByInstrumentSymbol

GET /v1/prediction-markets/combos/{instrumentSymbol} · Public

Look up a combo by its instrument symbol. Returns a ComboResponse with a contract metadata object and a legs array.

Code
const combo = await client.predictions.getComboByInstrumentSymbol({
  instrumentSymbol: "GEMI-CMB-0526-A7F3B2C1D4E5",
});

console.log(combo.contract.contractTicker);
console.log(combo.contract.contractStatus);

for (const leg of combo.legs) {
  console.log(leg.contractId, leg.requiredOutcome, leg.legOutcome);
}

Tip — legs[*].comboId values are bigint.

Auto-retry — This GET endpoint automatically retries on 429/502/503/504 status codes.

listCombos

GET /v1/prediction-markets/combos · Public

List available combos with optional filters. Returns a ListCombosResponse with a .combos array and a .pagination object.

Code
// All active combos (default status)
const result = await client.predictions.listCombos();

// Filter by status (capitalized: "Active", "Settled", "Voided")
const filtered = await client.predictions.listCombos({
  status: "Active",
  limit: 25,
  offset: 0,
});

// Filter by underlying contract ID (numeric bigint)
const byContract = await client.predictions.listCombos({
  contractId: 101n,
  instrumentRegistered: true,
});

for (const combo of filtered.combos) {
  console.log(combo.contract.contractTicker, combo.legs.length);
}

Tip — The status filter value is capitalized (e.g. "Active", not "active"). The contractId filter is a numeric ID (bigint), not a ticker string.

Auto-retry — This GET endpoint automatically retries on transient failures.

What's next

• Events & Discovery — browse and search prediction market events
• Order Management — place, cancel, and query orders
• Positions & Terms — open and settled positions, terms acceptance
• Data Types — why combo.id and contractId are bigint
• Request Validation — how client-side validation works