compute_price
Compute a price for a product/context via the Last Price Pricing Compute Network. Returns the computed price, the function that produced it, token metering/cost, and a trace listing each stage the request passed through (cache, route, execute, fallback, constrain, meter). For a competitor offer, put competitor_price, competitor_currency and competitive_action in metadata, then supply min_price or unit_cost with target_margin_pct. Missing business inputs return an error naming them. To pay for this one call with x402 instead of a key or a balance, pass payment: a signed payment for the price it asks (call it without payment to read what it asks). Where quote expiry is switched on for the workspace, the result carries valid_until (RFC 3339): quote or charge the price only before then, and compute again after. Pass intent (the limit the buyer approved) to learn whether the price fits it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Optional geography hint, e.g. US. | |
| payer | No | Optional. Who pays, as distinct from who calls: the agent from its own wallet, a person by card, or a company billed later. Where this is switched on it reaches buyer-aware pricing as metadata.payer and the answer echoes it. | |
| intent | No | Optional. The spending limit the buyer approved, such as a card network or payment rail mandate. Where this is switched on for the workspace, the result says whether the price fits it, with the reasons when not, and a signed quote binds the same so an issuer or buyer can check it. | |
| channel | No | Optional. The sales channel the price is for, such as a shopping agent or an agent marketplace. When your workspace saved a rate for it with set_channel_rates and channel pricing is on, the price is raised so you keep the same amount after the channel's cut. | |
| payment | No | Optional. The signed x402 payment, base64, as sent in an X-PAYMENT or PAYMENT-SIGNATURE header; or, where the answer offers MPP tempo, the whole Payment-Authorization value ("Payment " and the credential). Omit it to read what the call costs and how to pay; nothing is charged until you send it. | |
| routing | No | Optional. Which functions may answer this one call, by UUID from list_functions. A call these leave with no function is refused, naming why, before anything runs or is charged. Where routing preferences are not yet on for your workspace they are ignored. | |
| currency | Yes | Three-letter ISO currency code, e.g. USD. | |
| metadata | No | Optional context. For competitive pricing: competitor_price, competitor_currency and competitive_action (match or undercut); undercut requires undercut_pct. Confirm product comparability before calling. Or send market_query (the job, in plain words) instead of competitor_price: where market prices are switched on, the market is looked up first and the answer carries market_prices (low, median, high and the pages); with competitive_action and no competitor_price, the lowest market price is used to undercut and the median to match (market_reference: low, median or high chooses). | |
| max_price | No | Optional maximum acceptable price. | |
| min_price | No | Optional minimum acceptable price. A competitive offer needs this or a declared unit_cost and target_margin_pct. | |
| unit_cost | No | What the work costs you. It lets lastprice/cost-plus price with no current_price, which is the usual case when pricing a task you are about to run. Routing picks a function that can use it; to require cost-plus, pass its UUID from list_functions as function_id. | |
| buyer_type | No | Optional. Who the price is for: an AI agent or a person. Recorded with the quote only. | |
| no_explore | No | If true, give this price exactly as computed, without the small per-call variation a workspace may run so learned pricing can learn what buyers will pay (see get_price_exploration). | |
| product_id | No | Optional identifier of what is being priced. | |
| buyer_agent | No | Optional. The buying agent, e.g. chatgpt or agent.example.com. A label recorded with the quote only (while its release flag is on); never sent to the pricing function. | |
| function_id | No | Optional explicit pricing function UUID to use. | |
| product_type | No | Optional category. Defaults to "custom". | |
| current_price | No | The current or reference price. Optional: functions that price relative to an incumbent need it, but lastprice/cost-plus prices from unit_cost instead. | |
| outcome_terms | No | Optional, for a price charged per outcome. When the outcome counts as failed and what is owed then. Where outcome terms are switched on for the workspace, the result carries outcome_terms: these terms normalised, the deadline as a time, the amount owed on timeout, and which terms are missing (complete is false without success_definition, resolve_by and on_timeout). Sending it marks the price as an outcome price; so does metadata.unit "outcome". | |
| idempotency_key | No | Optional. A new value (e.g. a UUID) for each call you mean to make; send the SAME value if you retry after a timeout or error you cannot interpret, and the call is computed and charged once. Ignored without a credential. | |
| learned_routing | No | Optional. With routing_preference cheapest, fastest, round robin or weighted, let the router learn which of the functions that strategy chooses from serves your workspace best (from your own routed calls), falling back to the strategy while there is too little data. Ignored for any other preference or a function_id, and until learned routing is released for your workspace. get_learned_routing with strategy shows what it learned. | |
| customer_segment | No | Optional segment, e.g. enterprise. | |
| target_margin_pct | No | Margin on price for cost-plus, not markup on cost: price = unit_cost / (1 - margin). Defaults to 30. | |
| routing_preference | No | How to route across pricing functions. Defaults to "default". | |
| include_explanation | No | If true, ask for an explanation and confidence with the price. | |
| include_buyer_envelope | No | If true, and metadata.category names a category, the result carries buyer_envelope: what buyers' own spend checks allowed in that category (p25 to p75, the median, and how often checks were refused over a limit, pooled over 5 or more buyer workspaces; no numbers below 5) and where this price sits. A limit, not a valuation: it never changes the price. Where it is not switched on for the workspace it is ignored. |