Quote Negotiation: How Sellers Price and Sign Requests

Before committing to a payment, a buyer can ask your seller for a firm price — a signed, time-limited Quote that locks in the exact amount for a specific piece of work. This handshake protects both sides: the buyer knows exactly what it will pay before submitting a transaction, and you as the seller have cryptographically bound the buyer’s request to a price you approved. The quote endpoint is free to call, so buyers are encouraged to negotiate before every paid request.

Quote Flow

The negotiation follows four steps:

Buyer sends a quote request. The buyer POSTs to your /a2a/quote endpoint, describing the work it wants done (token estimates, unit count) and optionally naming a maximum amount it is willing to pay.
Seller prices the work. Your seller calls priceFor(model, estimate) using the pricing model defined for the requested endpoint, producing the list price in atomic units.
Seller signs and returns the Quote. The seller signs the canonical quote body with its Hedera account key and returns the Quote object. The countered flag tells the buyer whether the seller accepted a counter-offer below list price.
Buyer verifies the signature. The buyer checks the quote signature against signerPublicKey, then queries the Hedera mirror node to confirm that signerPublicKey is the active key for the payTo account named in the listing. This proves the quote was issued by the entity that owns the payment destination.

Request Format

Send a JSON body to POST /a2a/quote:

string

Your UAID (e.g. uaid:aid:...). Optional — provided for the seller’s information and recorded in logs, but not required for the quote to be processed.

string

required

The stable identifier of the endpoint you want to call, as declared in the seller’s ServiceListing. For example: "infer" or "hbar-rate".

object

Your estimate of the work to be done. The seller uses this to compute the price. All sub-fields are optional and default to 0 (or 1 for units).

Show estimate fields

integer

Estimated number of input tokens in your request body. Use estimateChatInput() from @agora402/shared to compute this from your messages array.

integer

The max_tokens budget you plan to pass to the endpoint. Used as the output cost basis for per-token pricing.

integer

Number of discrete units for per-unit pricing endpoints (e.g. number of queries). Minimum 1.

string

Your ceiling price in atomic units of asset (e.g. "9000000" for 0.09 HBAR). If you pass this and it is below the seller’s list price, the seller treats it as a counter-offer. Omit to accept the list price.

string

default:"0.0.0"

The HTS asset ID to pay with. "0.0.0" means native HBAR. Must match one of the accepts entries on the endpoint.

Response Format

A successful 200 response body:

Quote object

required

The signed quote. Pass quote.quoteId in your payment request body to pin the payment to this quoted amount.

Show Quote fields

string

Unique identifier for this quote (at least 8 characters). Pass this as quoteId in your paid request body to use the quoted price instead of the live list price.

string

The seller’s UAID (uaid:aid:...). Matches the uaid in the seller’s ServiceListing.

string

The endpoint this quote is valid for.

string

The Hedera CAIP-2 network identifier: "hedera:testnet" or "hedera:mainnet".

string

The asset ID the quote is denominated in (e.g. "0.0.0" for HBAR).

string

The agreed price in atomic units as a decimal string (e.g. "8500000"). This is the exact amount that will appear in the 402 challenge when you submit the request with quoteId.

integer

Unix timestamp (seconds) after which the quote is no longer valid. Submit your payment before this time.

object

The estimate and pricing inputs the seller used to compute amount, echoed back for auditability. Useful for verifying the seller priced what you described.

string

Hex-encoded ECDSA or ED25519 signature over the canonical quote body, produced by the seller’s Hedera account key.

string

Hex-encoded DER public key that produced signature. Verify this key is the active key of the seller’s payTo account on the mirror node.

boolean

required

true if the seller accepted a counter-offer below its list price. false if the returned amount equals the seller’s computed list price. Use this to know whether you negotiated a discount.

Counter-Offers

If you pass a maxAmount below the seller’s list price, the seller’s quote engine compares your ceiling against an internal floor:

Above the floor — the seller accepts your counter. The quote amount is set to your maxAmount and countered is true.
Below the floor — the seller rejects with HTTP 409 Conflict. The response body includes minimumAmount (the seller’s floor) and listPrice so you can see the range and decide whether to retry at a higher ceiling.

HTTP 409 response when counter is below the floor

{
  "error": "counter below floor",
  "minimumAmount": "7000000",
  "listPrice": "10000000"
}

Using a Quote in a Paid Request

Once you have a quote, include quoteId in the JSON body of your paid request. The seller’s middleware reads quoteId from the request body and uses quote.amount as the 402 challenge price instead of re-computing the live price from the request:

Requesting a quote and using it

// Step 1: request the quote
const resp = await fetch('http://localhost:4402/a2a/quote', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    endpointId: 'infer',
    estimate: { inputTokens: 120, maxOutputTokens: 256 },
    asset: '0.0.0',
    maxAmount: '9000000',  // counter at slightly below list price
  }),
});
const { quote, countered } = await resp.json();
console.log(`Quoted ${quote.amount} tinybars (countered: ${countered})`);

// Step 2: use the quoteId in the paid request body
const inferResp = await fetch('http://localhost:4402/v1/infer', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    quoteId: quote.quoteId,          // pins payment to the quoted amount
    messages: [
      { role: 'user', content: 'Explain x402 in one sentence.' },
    ],
    max_tokens: 256,
  }),
  // @x402/fetch intercepts the 402 and attaches the payment automatically
});

Quotes are single-use and time-limited. You must submit your payment request before expiresAt (a Unix timestamp in seconds). Once a quote is consumed by a settled payment, it cannot be reused — submit a new quote request for your next call. If your request arrives after expiresAt, the seller will re-price it at the current list price instead of the quoted amount.

If you skip the quote step entirely, the seller prices the request live from the request body using priceFor. This is perfectly valid — quoting is optional, not mandatory. Use quotes when you need budget predictability or want to lock in a negotiated discount before committing.

Get started

Setup

Seller guide

Buyer guide

Integrations

Quote Negotiation: How Sellers Price and Sign Requests

Quote Flow

Request Format

Response Format

Counter-Offers

Using a Quote in a Paid Request

​Quote Flow

​Request Format

​Response Format

​Counter-Offers

​Using a Quote in a Paid Request

Quote Flow

Request Format

Response Format

Counter-Offers

Using a Quote in a Paid Request