# 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](/tools/typescript-sdk/deep-dives/request-validation).

```ts
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](/tools/typescript-sdk/deep-dives/request-validation).

> **Tip** — Response fields `combo.id`, `combo.instrumentId`, and `combo.legs[*].comboId` are `bigint`. See [Data Types](/tools/typescript-sdk/deep-dives/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.

```ts
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.

```ts
// 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](/tools/typescript-sdk/reference/predictions/events-and-discovery) — browse and search prediction market events
- [Order Management](/tools/typescript-sdk/reference/predictions/order-management) — place, cancel, and query orders
- [Positions & Terms](/tools/typescript-sdk/reference/predictions/positions-and-terms) — open and settled positions, terms acceptance
- [Data Types](/tools/typescript-sdk/deep-dives/data-types) — why `combo.id` and `contractId` are `bigint`
- [Request Validation](/tools/typescript-sdk/deep-dives/request-validation) — how client-side validation works