List Midnight offer groups for a user

Cursor-paginated list of a user's offer groups with nested offers. The statuses filter accepts one or more lifecycle states with OR semantics. The deprecated singular status parameter is a single-value alias; requests containing both are rejected. Omitting both defaults to active for backward compatibility.

Lifecycle is derived from every latest offer revision before market, asset, maturity, type, callback, or listing filters are applied. cancelled has highest priority and requires an explicit SetConsumed(type(uint128).max) event; a Take reaching the same numeric value remains filled. Otherwise, a group is filled when every latest leg has no remaining capacity. It is active when at least one remaining leg has started and is at or before both its expiry and non-zero maturity. It is scheduled when no leg is active but at least one remaining leg starts in the future without having expired or matured. All remaining groups are expired. Active takes remain valid at exact expiry or maturity, matching the onchain inclusive boundary.

Nested offers are lifecycle-targeted for list results: active returns live remaining-capacity legs, scheduled returns future remaining-capacity legs, filled and cancelled return all latest legs, and expired returns terminal expired or matured legs. Active and scheduled group expiry is the maximum not-yet-ended latest-offer horizon; terminal statuses use the complete latest set. Requesting all five statuses returns every indexed group exactly once.

Callbacks. A group has callback.type=blue_buy only when every latest offer considered for the lifecycle has the same callback address and data, contains canonical Blue market parameters with the matching loan token, and the earliest indexed registration from the official factory names the maker as owner at or before the offer's creation block. Registration transaction or log order within the same block is intentionally ignored. The callback is null when any condition fails. Verified callbacks include their address, decoded Blue market parameters, and derived Blue market id.

Types. Group type is derived from the shared buy and reduce_only values across all offers considered for the requested lifecycle. buy and sell mean reduce_only=false; buy_reduce_only and sell_reduce_only mean reduce_only=true. For the portfolio, buy and sell_reduce_only represent lend orders and secondary exits, while sell and buy_reduce_only represent borrow orders and secondary exits. Inconsistent groups return type: null and do not match the types filter. This describes offer intent, not the maker's current position.

Filters. market_ids filters the group page to groups containing at least one offer in the requested lifecycle and any requested market, but does not narrow nested sibling offers. chain_ids and groups filter the group page and nested offers. loan_assets, collateral_assets, exact maturities, and the inclusive unix-second bounds maturity_gte and maturity_lte filter both the group page and returned offers in the requested lifecycle for every status, and combine with other filters using AND semantics. Offers with no maturity deadline have maturity 0: they match any maturity_lte and are excluded by maturity_gte of 1 or more. types accepts comma-separated offer-group types with OR semantics and combines with other filters using AND semantics without narrowing nested offers. callback_type=blue_buy keeps only groups with verified Blue callback metadata. listed=true requires every lifecycle-matching offer in a group to be on a listed market; listed=false requires at least one lifecycle-matching unlisted offer. Address filters match across all chains unless chain_ids also narrows the query; lowercase addresses are checksummed. Group expiry is not narrowed by offer filters; active results use the active-eligible latest offer set, while expired results use the complete latest offer set. created_at_gte and created_at_lte filter by the first matching offer created in each group. market_ids, loan_assets, collateral_assets, maturities, groups, and types are capped at 20 values. Each offer includes both market_id and the immutable market config used to derive it, because uncreated markets cannot be decoded from market_id alone.

Ratifier data. Each nested offer includes the exact per-offer ratifier_data bytes originally submitted, plus parsed_ratifier_data, a structured view discriminated by ratifier_type. The type is identified by matching ratifier against the chain's known Midnight ratifier deployments: rate_v1 exposes rate_per_second_wad and allowed_taker, price_v1 exposes allowed_taker (the offer-level tick is the ratified price), and ecrecover and setter expose only their type. A zero allowed_taker means any taker may take the offer. An unrecognized ratifier address returns unknown; a recognized address whose ratifier_data cannot be decoded returns invalid with expected_ratifier_type.

Pagination. Response follows the list envelope: { cursor, data }. Pagination is over groups; nested offers are not split across pages. Sort groups with sort_by=id|created_at and sort_direction=asc|desc.

Path Parameters

Query Parameters

Response Body