Search supply
supply_searchRead-onlyIdempotent
Multi-provider discovery (live REAL merchants by default). Returns a ranked page (default limit=30, max 100) with total/has_more/next_offset. Follow next.args (search_id+offset+limit) to page without re-fanout. Optional fetch_limit (max 300) deepens the upstream pull on new searches. Pass include_sandbox=true only to append DEMO/SANDBOX test merchants at the bottom (test_offer=true). Always pass agent_id for mandate-aware badges. Carry search_id through supply_details / order_execute / order_feedback.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size of ranked offers to return (default 30, max 100) | |
| query | No | Product search query, e.g. USB-C charger 65W. Required for a new search; omit when paging with search_id + offset | |
| budget | No | Max total budget — number means USD; or { amount, currency } | |
| offset | No | 0-based offset into the ranked set for this search_id (default 0). For page 2+, pass search_id from the prior response and follow next.args | |
| country | No | ISO country for ships-to, e.g. US | |
| agent_id | No | Agent id for mandate-aware badges (always pass when available) | |
| quantity | No | Desired quantity (default 1) | |
| search_id | No | Resume paging into a prior ranked set (with offset>0, or offset 0 without query). New searches with query mint a fresh search_id | |
| fetch_limit | No | Optional override for per-merchant upstream pull (default max(20, limit*2), max 300). Ignored when paging via search_id+offset | |
| payable_with | No | Filter to rails the agent can pay with, e.g. ["x402"] | |
| session_token | No | Session token from agent_authenticate — required whenever agent_id is passed | |
| include_sandbox | No | Include DEMO/SANDBOX merchants (listed last, test_offer=true). Default false — live REAL merchants only. Use only when testing Conduit checkout flows. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | ||
| next | No | ||
| error | No | ||
| limit | No | ||
| total | No | ||
| detail | No | ||
| offers | No | ||
| offset | No | ||
| country | No | ||
| partial | No | ||
| degraded | No | ||
| has_more | No | ||
| withheld | No | ||
| search_id | No | ||
| next_offset | No | ||
| recommended | No | ||
| badge_counts | No | ||
| country_default | No | ||
| include_sandbox | No | ||
| sandbox_included | No |