Trade Idea

Pear surfaces ready-to-trade baskets and pairs so you can seed ideas instead of building every basket by hand.

Endpoints

Endpoint	Returns
`GET /markets/baskets`	Selector-ready baskets: materialized baskets, then generated 1-long / 1-short pairs, each enriched with live market data.
`GET /markets`	Single-instrument markets joined with cached price, funding, and 24h stats.
`GET /saved-baskets`	Your saved basket templates.

Browse baskets

curl "https://pro-gateway.pearprotocol.io/markets/baskets?connector=hyperliquid&search=BTC&limit=20"

{
  "limit": 20,
  "offset": 0,
  "count": 137,
  "markets": [
    {
      "connector": "hyperliquid",
      "basketKey": "232a1acc52e088e456f29b96abd05d6169a8be4c21f8d7f1d3ee1c71afd47fe9",
      "displaySymbol": "BTC/ETH",
      "legs": [
        { "id": "0", "symbol": "BTC", "side": "BUY" },
        { "id": "1", "symbol": "ETH", "side": "SELL" }
      ],
      "price": "24.3117",
      "priceChange24h": "-1.4208",
      "weightRatio": "24.3117",
      "weightRatioChange24h": "-1.4208",
      "netFunding": "0.0000160163",
      "volume24h": "18420000",
      "openInterest": "5210000",
      "tradeability": { "status": "tradable", "reason": null },
      "updatedAt": 1787678001408,
      "hasMaterializedStats": true
    }
  ]
}

Each leg gives you both identifiers: id is the instrument ID you put in a trade leg's symbol field, and symbol is the ticker you show a user. See Instrument ID.

Field	Use it for
`basketKey`	A stable hash of the basket's legs. See Position Key. Pass a list of them to `POST /markets/baskets/positions` to see how many traders have opened each.
`weightRatio`	The basket's current weighted ratio.
`netFunding`	The basket's combined funding cost. See Net Funding.
`tradeability`	`tradable`, `reduce_only`, or `not_tradable`, with a reason. Check it before you place an order.

connector is required on both market endpoints, and on GET /prices and GET /funding. Filter with search, and page with limit and offset. Unlike the account endpoints, this one pages by offset, not by cursor.

scope defaults to tradable, so by default the list already excludes everything tradeability would warn you about. Pass scope=all to see reduce_only and not_tradable rows as well, and use reduce_only or not_tradable to list only those. Even at the default, check tradeability before you order: a market can degrade between the fetch and the order.

GET /markets returns { markets, totals }, where totals is { markets, volume24h, openInterest } for the connector.

How many traders hold a basket

POST /markets/baskets/positions counts the openings of each basket you name:

{
  "basketKeys": ["232a1acc52e088e456f29b96abd05d6169a8be4c21f8d7f1d3ee1c71afd47fe9"],
  "connector": ["hyperliquid"]
}

basketKeys is required: 1 to 500 keys, each 64 lowercase hex characters, exactly as GET /markets/baskets reports them. You can also derive one locally, without calling /markets/baskets, with deriveBasketKey(longInstrumentIds, shortInstrumentIds) from @pear-protocol/utils. connector is optional; omit it to sum every venue, but do not send an empty array.

The response is { counts: [{ basketKey, opened, traders }] }, one row per requested key in request order. A basket nobody has opened reads zero.

These are cumulative popularity counts, not open interest. opened counts positions ever opened and traders counts distinct traders. Closing a position never decrements either. Counts are recorded when a Pear open completes, so a position opened directly on the venue does not appear. When you sum several connectors, a trader active on two venues counts once per venue.

Turn an idea into a trade

Take the leg ids straight into POST /trade/open:

{
  "type": "MARKET",
  "legs": [
    { "symbol": "0", "side": "BUY",  "mode": "USD", "amount": "500" },
    { "symbol": "1", "side": "SELL", "mode": "USD", "amount": "500" }
  ]
}

Confirm current pricing with GET /prices and GET /funding first, and resolve any ticker you hold to an instrument ID with GET /instruments/symbol-to-id-map.

Saved baskets

Store a basket template on the trade account and reuse it:

{
  "name": "BTC over ETH",
  "legs": [
    { "symbol": "0", "side": "BUY",  "weight": 0.5 },
    { "symbol": "1", "side": "SELL", "weight": 0.5 }
  ]
}

Create with POST /saved-baskets (201), update with PATCH /saved-baskets/{id} (200), and delete with DELETE /saved-baskets/{id} (204). A saved basket holds weights, not sizes, so you pick the notional at the moment you trade it.

Saved baskets belong to a trade account, not to the user. Every call on this group needs the x-trade-account-id header, and the list returns only that account's baskets. GET /saved-baskets takes no pagination and returns them all, most recently updated first.

Field	Constraint
`name`	Trimmed, 1 to 48 characters, unique per trade account, compared case-insensitively.
`legs`	1 to 20 legs. No symbol may repeat.
`weight`	Greater than 0 and at most 1. All legs must sum to exactly 1.

PATCH needs at least one of name or legs, and replaces legs wholesale.

Weights

A leg's weight is its share of the basket's total gross notional, and the weights of all legs must sum to exactly 1. They do not sum to 1 within each side. A three-leg basket of two longs and one short is 0.25 / 0.25 / 0.5, not 0.5 / 0.5 / 1.0. Anything else returns 400 with The sum of weights must be exactly 1.

A basket's direction, not its absolute price, is what you trade. See Weighted Price Ratio.

Narrative baskets (agents)

Agent Pear's narrative baskets, thematic long/short ideas generated from market signals, are available to LLM agents through the Orchard MCP (discover_assets, list_baskets).