# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Agoragentic Agent OS and Marketplace Router Commerce API
  version: 1.0.0
extends: openapi/agoragentic-com-commerce-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 66
- target: $.paths['/commerce'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my overall buyer commerce summary
      effect: read
      questions:
      - What's my wallet balance, active subscriptions and recent receipts on Agoragentic in one view?
      - Is there a single summary of everything I've bought and am entitled to?
      instructions:
      - text: Give me my unified buyer commerce summary.
      - text: Show my wallet balance, subscriptions, entitlements and recent receipts together.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/account'].get
  update:
    x-apievangelist-phrasing:
      intent: View my agent operating account
      effect: read
      questions:
      - What does my agent's operating account look like while paid execution is frozen?
      - Can I still read my account summary when platform custody is unavailable?
      instructions:
      - text: Show my agent operating account.
      - text: Read my operating account summary and its recommendation fields.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/identity'].get
  update:
    x-apievangelist-phrasing:
      intent: View my portable agent identity
      effect: read
      questions:
      - How portable is my agent's identity, and is it ready to sign?
      - What passport proof state and buying identities does my agent have?
      instructions:
      - text: Show my agent's portable identity summary.
      - text: Check my signing readiness and passport proof state.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/identity/check'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a counterparty's identity and trust
      effect: read
      questions:
      - Before dealing with another agent, can I check whether I should allow, supervise or block it?
      - Can I look up a counterparty by wallet address instead of agent ID?
      instructions:
      - text: Check the identity portability of agent {agent_id}.
        slots:
          agent_id: requestBody.agent_id
      - text: Tell me whether to trust the counterparty with wallet {wallet_address}.
        slots:
          wallet_address: requestBody.wallet_address
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/learning'].get
  update:
    x-apievangelist-phrasing:
      intent: Review my learning and reputation memory
      effect: read
      questions:
      - What lessons should my agent take from its failed invocations and bad reviews?
      - Can I see the saved learning notes alongside my reputation signals?
      instructions:
      - text: Show my learning queue and reputation memory.
      - text: List the lessons pending from reviews, flags and failed jobs.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/learning/candidates'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate candidate learning notes
      effect: read
      questions:
      - Can Agent OS draft learning notes for me from my recent failures and denials?
      - Is it possible to limit candidate lessons to certain source types, like reviews only?
      instructions:
      - text: Suggest learning-note candidates from my recent feedback.
      - text: Generate up to {limit} learning candidates from {source_types}.
        slots:
          limit: requestBody.limit
          source_types: requestBody.source_types
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/learning/notes'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a learning note to memory
      effect: write
      questions:
      - How do I save a lesson my agent learned so it remembers it later?
      - Where do durable learning notes get stored?
      instructions:
      - text: 'Save this learning note: {input}.'
        slots:
          input: requestBody.input
      - text: Record a durable lesson in my vault memory.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/learning/skill-recipes/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export a listing as a skill recipe
      effect: read
      questions:
      - Can I turn a marketplace listing into a reusable skill recipe object?
      - What's included when a listing is exported as a skill recipe?
      instructions:
      - text: Export listing {listing_id} as a skill recipe.
        slots:
          listing_id: requestBody.listing_id
      - text: Convert the listing with slug {slug} into a skill recipe for my memory.
        slots:
          slug: requestBody.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/learning/skill-recipes/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import a skill recipe into vault memory
      effect: write
      questions:
      - How do I save a skill recipe into my agent's memory?
      - Can I export and import a listing's recipe in a single call?
      instructions:
      - text: Import this skill recipe {recipe} into my vault memory.
        slots:
          recipe: requestBody.recipe
      - text: Save the recipe for listing {listing_id} under key {key} in namespace {namespace}.
        slots:
          listing_id: requestBody.listing_id
          key: requestBody.key
          namespace: requestBody.namespace
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/reconciliation'].get
  update:
    x-apievangelist-phrasing:
      intent: Reconcile my agent's spend and runway
      effect: read
      questions:
      - How much has my agent spent recently, and how long will my wallet last?
      - Can I see spend forecasts and recurring commitments over a set number of days?
      instructions:
      - text: Show my accounting and reconciliation summary.
      - text: Break down my spend over the last {days} days.
        slots:
          days: query.days
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/procurement'].get
  update:
    x-apievangelist-phrasing:
      intent: View my procurement policy and approvals
      effect: read
      questions:
      - What spend policy is my agent operating under right now?
      - Which purchase approvals am I waiting on, and which are waiting on me as supervisor?
      instructions:
      - text: Show my procurement control-plane summary.
      - text: List my spend policy, runway and outstanding purchase approvals.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/procurement/check'].post
  update:
    x-apievangelist-phrasing:
      intent: Preflight whether a purchase is allowed
      effect: read
      questions:
      - Would buying a specific listing be allowed under my budget and wallet policy?
      - Can I test a purchase at a quoted cost before committing to it?
      instructions:
      - text: Check whether I'm allowed to buy listing {listing_id}.
        slots:
          listing_id: requestBody.listing_id
      - text: Preflight buying capability {capability_id} at {quoted_cost_usdc} USDC.
        slots:
          capability_id: requestBody.capability_id
          quoted_cost_usdc: requestBody.quoted_cost_usdc
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/purchase-sessions'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a Router Checkout purchase session
      effect: write
      questions:
      - How do I start buying an outcome instead of picking a specific provider?
      - Can I set constraints and a category when I open a checkout session?
      instructions:
      - text: Open a checkout session to achieve {goal}.
        slots:
          goal: requestBody.goal
      - text: Start a Router Checkout session for {goal} in category {category} with constraints {constraints}.
        slots:
          goal: requestBody.goal
          category: requestBody.category
          constraints: requestBody.constraints
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/purchase-sessions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a Router Checkout session
      effect: read
      questions:
      - How do I check the state and option groups of a checkout session I opened?
      - What stage is my Router Checkout purchase session at?
      instructions:
      - text: Show checkout session {id}.
        slots:
          id: path.id
      - text: Read the options and status of purchase session {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/purchase-sessions/{id}/selections'].post
  update:
    x-apievangelist-phrasing:
      intent: Choose options in a checkout session
      effect: write
      questions:
      - How do I pick provider, quality and fallback options before getting a quote?
      - Does selecting checkout options spend anything?
      instructions:
      - text: Record selections {selections} on checkout session {id}.
        slots:
          selections: requestBody.selections
          id: path.id
      - text: Set my provider and quality choices for session {id} to {selections}.
        slots:
          id: path.id
          selections: requestBody.selections
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/purchase-sessions/{id}/quote'].post
  update:
    x-apievangelist-phrasing:
      intent: Build a quote for a checkout session
      effect: write
      questions:
      - How do I get a priced quote bundle and execution plan for my checkout choices?
      - Where are max total and per-step budget caps enforced in Router Checkout?
      instructions:
      - text: Build a quote bundle for checkout session {id}.
        slots:
          id: path.id
      - text: Quote session {id} against my selected options without spending.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/purchase-sessions/{id}/approve'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve a quoted checkout session
      effect: write
      questions:
      - How do I sign off on a quoted checkout before it runs?
      - Does approving a checkout session execute it?
      instructions:
      - text: Approve quoted checkout session {id}.
        slots:
          id: path.id
      - text: Approve session {id} as {approved_by} because {reason}.
        slots:
          id: path.id
          approved_by: requestBody.approved_by
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/purchase-sessions/{id}/execute'].post
  update:
    x-apievangelist-phrasing:
      intent: Execute an approved checkout quote
      effect: write
      questions:
      - When can I actually run a paid Router Checkout quote bundle?
      - What must be true before a checkout session is allowed to spend?
      instructions:
      - text: Execute the approved quote bundle for session {id} once paid execution is enabled.
        slots:
          id: path.id
      - text: Run checkout session {id} now that the owner has approved spend.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/purchase-sessions/{id}/receipts'].get
  update:
    x-apievangelist-phrasing:
      intent: Get receipts for a checkout session
      effect: read
      questions:
      - Where do I find the receipts from a Router Checkout purchase?
      - Can I pull the full receipt bundle for one checkout session?
      instructions:
      - text: Fetch the receipt bundle for checkout session {id}.
        slots:
          id: path.id
      - text: Show the receipts produced by purchase session {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/purchase-sessions/{id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a checkout session
      effect: destructive
      questions:
      - How do I abandon a Router Checkout session before it executes?
      - Can I cancel a checkout session that is already executing?
      instructions:
      - text: Cancel checkout session {id}.
        slots:
          id: path.id
      - text: Abort purchase session {id} before it runs.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe the Agent Commerce Interchange
      effect: read
      questions:
      - How does the Agent Commerce Interchange lifecycle work from capability card to receipt?
      - What stages does an interchange transaction go through?
      instructions:
      - text: Show the Agent Commerce Interchange descriptor.
      - text: Explain the interchange lifecycle surfaces available to me.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/intents/fold'].post
  update:
    x-apievangelist-phrasing:
      intent: Fold a request into a no-execution plan
      effect: read
      questions:
      - Can I turn a free-text purchase request into a typed transaction plan without running it?
      - Does intent folding use an LLM to classify my request?
      instructions:
      - text: Fold the request {request} into a deterministic plan preview.
        slots:
          request: requestBody.request
      - text: Preview a transaction plan for {request} under mandate {mandate_id}.
        slots:
          request: requestBody.request
          mandate_id: requestBody.mandate_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/capability-cards'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a capability card
      effect: write
      questions:
      - How do I create a capability card from one of my marketplace listings?
      - When does a capability card become eligible for transaction plans?
      instructions:
      - text: Create a capability card for listing capability {capability_id}.
        slots:
          capability_id: requestBody.capability_id
      - text: Make a capability card named {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/capability-cards/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a capability card
      effect: read
      questions:
      - How do I look at the details of one capability card?
      - Is a particular capability card eligible for invocation?
      instructions:
      - text: Show capability card {id}.
        slots:
          id: path.id
      - text: Read the pricing and eligibility of capability card {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/mandates'].post
  update:
    x-apievangelist-phrasing:
      intent: Draft a buyer spending mandate
      effect: write
      questions:
      - How do I set per-call, daily and total budget caps for a buyer agent?
      - Can a mandate restrict which capability cards and actions an agent may use?
      instructions:
      - text: Draft a mandate for buyer {buyer_agent_id} on deployment {deployment_id} with idempotency key {idempotency_key}.
        slots:
          buyer_agent_id: requestBody.buyer_agent_id
          deployment_id: requestBody.deployment_id
          idempotency_key: requestBody.idempotency_key
      - text: Create a mandate for agent {buyer_agent_id} on {deployment_id} with budget {budget}, key {idempotency_key}.
        slots:
          buyer_agent_id: requestBody.buyer_agent_id
          deployment_id: requestBody.deployment_id
          budget: requestBody.budget
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/mandates/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a buyer mandate
      effect: read
      questions:
      - How do I see the caps and allowed actions on a mandate?
      - Has a particular mandate been reviewed by its owner yet?
      instructions:
      - text: Show mandate {id}.
        slots:
          id: path.id
      - text: Read the budget caps and review state of mandate {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/mandates/{id}/review'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve or reject a mandate as owner
      effect: write
      questions:
      - How does a mandate owner approve or reject a draft mandate?
      - Does a mandate review produce signed evidence?
      instructions:
      - text: Record decision {decision} on mandate {id}.
        slots:
          decision: requestBody.decision
          id: path.id
      - text: Review mandate {id} with decision {decision} and reason {reason}.
        slots:
          id: path.id
          decision: requestBody.decision
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/plans'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a transaction plan
      effect: write
      questions:
      - How do I start a transaction plan that ties a capability card to a mandate?
      - What states does an interchange transaction plan move through?
      instructions:
      - text: Create a plan for card {capability_card_id} under mandate {mandate_id} with key {idempotency_key}.
        slots:
          capability_card_id: requestBody.capability_card_id
          mandate_id: requestBody.mandate_id
          idempotency_key: requestBody.idempotency_key
      - text: Start a plan on card {capability_card_id}, mandate {mandate_id}, capped at {max_amount}, key {idempotency_key}.
        slots:
          capability_card_id: requestBody.capability_card_id
          mandate_id: requestBody.mandate_id
          max_amount: requestBody.max_amount
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/plans/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a transaction plan
      effect: read
      questions:
      - What state is my interchange transaction plan in right now?
      - How do I look up one transaction plan by its ID?
      instructions:
      - text: Show transaction plan {id}.
        slots:
          id: path.id
      - text: Read the current state of interchange plan {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/plans/{id}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List a transaction plan's audit events
      effect: read
      questions:
      - Can I see the audit trail of state changes on a transaction plan?
      - Who moved a plan forward, and when?
      instructions:
      - text: List the audit events for plan {id}.
        slots:
          id: path.id
      - text: Show the last {limit} audit events on transaction plan {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/plans/{id}/advance'].post
  update:
    x-apievangelist-phrasing:
      intent: Advance a transaction plan one state
      effect: write
      questions:
      - How do I move a transaction plan to its next state with gate checks?
      - Can I advance a plan while platform custody is frozen?
      instructions:
      - text: Advance transaction plan {id} one state.
        slots:
          id: path.id
      - text: Move plan {id} to {target_state} if the gates pass.
        slots:
          id: path.id
          target_state: requestBody.target_state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/receipts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a minted interchange receipt
      effect: read
      questions:
      - How do I view the full receipt minted for my interchange transaction?
      - Can a buyer see the unredacted interchange receipt?
      instructions:
      - text: Show interchange receipt {id}.
        slots:
          id: path.id
      - text: Read the full minted receipt {id} for my transaction.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/public-receipts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a redacted public interchange receipt
      effect: read
      questions:
      - Can someone outside the deal verify an interchange receipt without seeing who was involved?
      - What does the anonymous public view of an interchange receipt include?
      instructions:
      - text: Show the public redacted interchange receipt {id}.
        slots:
          id: path.id
      - text: Get the anonymous cross-market proof for interchange receipt {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/receipts/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify an interchange receipt is untampered
      effect: read
      questions:
      - How can I tell whether an interchange receipt has been tampered with?
      - Can I verify a receipt JSON someone handed me rather than a stored ID?
      instructions:
      - text: Verify interchange receipt {receipt_id}.
        slots:
          receipt_id: requestBody.receipt_id
      - text: 'Check the hash and signature of this receipt JSON: {receipt}.'
        slots:
          receipt: requestBody.receipt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/admin/receipts/{id}/resign'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-sign an interchange receipt as admin
      effect: write
      questions:
      - How does an admin refresh the signature on an existing interchange receipt?
      - Does re-signing a receipt change its amount or hash?
      instructions:
      - text: Re-sign interchange receipt {id}.
        slots:
          id: path.id
      - text: Recompute the HMAC signature on receipt {id} as admin.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/capability-cards/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import external listings as capability cards
      effect: write
      questions:
      - Can I bring MCP tool or x402 service metadata in as capability cards?
      - Do imported capability cards ever become eligible for invocation?
      instructions:
      - text: 'Import these {source_kind} items as capability cards: {items}.'
        slots:
          source_kind: requestBody.source_kind
          items: requestBody.items
      - text: Normalize {items} from source kind {source_kind} into capability cards.
        slots:
          items: requestBody.items
          source_kind: requestBody.source_kind
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/mandates/{id}/spend-status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a mandate's spend status
      effect: read
      questions:
      - How much of a mandate's budget has been used so far?
      - Is a mandate close to hitting its daily or total cap?
      instructions:
      - text: Show the spend status of mandate {id}.
        slots:
          id: path.id
      - text: How much budget remains on mandate {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/mandates/{id}/suspend'].post
  update:
    x-apievangelist-phrasing:
      intent: Suspend a buyer mandate
      effect: destructive
      questions:
      - How do I stop a mandate from approving any new transaction plans?
      - What happens to plans already waiting on a mandate I suspend?
      instructions:
      - text: Suspend mandate {id}.
        slots:
          id: path.id
      - text: Freeze mandate {id} so no new plans get approved under it.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/plans/{id}/dispute'].post
  update:
    x-apievangelist-phrasing:
      intent: File a dispute on a transaction plan
      effect: write
      questions:
      - Can I open a dispute against an interchange transaction plan right now?
      - Why does filing a plan dispute currently return a 503?
      instructions:
      - text: File a dispute on transaction plan {id}.
        slots:
          id: path.id
      - text: Try to dispute plan {id} and tell me if filing is still unavailable.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/plans/{id}/suspend'].post
  update:
    x-apievangelist-phrasing:
      intent: Suspend a transaction plan as admin
      effect: destructive
      questions:
      - How does an admin halt a single transaction plan?
      - Can a non-admin suspend an interchange plan?
      instructions:
      - text: Suspend transaction plan {id}.
        slots:
          id: path.id
      - text: Halt interchange plan {id} as an admin.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/disputes/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read an interchange dispute
      effect: read
      questions:
      - How do I check the status of a dispute on an interchange plan?
      - Can the buyer see the details of a dispute?
      instructions:
      - text: Show dispute {id}.
        slots:
          id: path.id
      - text: Read the current state of interchange dispute {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/disputes/{id}/resolve'].post
  update:
    x-apievangelist-phrasing:
      intent: Resolve an interchange dispute
      effect: write
      questions:
      - How does a mandate owner close out a dispute?
      - Can I add a note when resolving a dispute?
      instructions:
      - text: Resolve dispute {id} with resolution {resolution}.
        slots:
          id: path.id
          resolution: requestBody.resolution
      - text: Settle dispute {id} as {resolution} and note {note}.
        slots:
          id: path.id
          resolution: requestBody.resolution
          note: requestBody.note
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/admin/sync-sources'].get
  update:
    x-apievangelist-phrasing:
      intent: Check discovery sync sources as admin
      effect: read
      questions:
      - Which external catalog sources are on the discovery allowlist and how fresh are they?
      - Are any discovery sync freshness alarms firing?
      instructions:
      - text: Show discovery sync sources and their status.
      - text: Report sync scheduler state and freshness alarms.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/admin/sync'].post
  update:
    x-apievangelist-phrasing:
      intent: Run an external discovery sync as admin
      effect: write
      questions:
      - How does an admin pull in listings from the approved external catalogs?
      - Is discovery sync a dry run unless I say otherwise?
      instructions:
      - text: Run a dry-run discovery sync.
      - text: Run discovery sync on sources {source_ids} with dry_run set to {dry_run}.
        slots:
          source_ids: requestBody.source_ids
          dry_run: requestBody.dry_run
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/interchange/providers/{id}/reputation'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a provider's interchange reputation
      effect: read
      questions:
      - How reputable is a provider within the commerce interchange?
      - What tier does a provider's advisory interchange score put it in?
      instructions:
      - text: Show the interchange reputation of provider {id}.
        slots:
          id: path.id
      - text: Get the advisory score and tier for provider {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/work-sessions'].post
  update:
    x-apievangelist-phrasing:
      intent: Open a bid-mode work session
      effect: write
      questions:
      - How do I post work and let providers bid on it?
      - Can I set a max price and bid window when requesting bids?
      instructions:
      - text: Open a bid-mode work session for {goal}.
        slots:
          goal: requestBody.goal
      - text: Request bids for {goal}, max {max_price_usdc} USDC, with a {bid_window} bid window.
        slots:
          goal: requestBody.goal
          max_price_usdc: requestBody.max_price_usdc
          bid_window: requestBody.bid_window
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/work-sessions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a bid-mode work session
      effect: read
      questions:
      - How do I check the spec and status of work I posted for bids?
      - Is my bid-mode work session still accepting bids?
      instructions:
      - text: Show work session {id}.
        slots:
          id: path.id
      - text: Read the work spec and status of bid session {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/work-sessions/{id}/bids'].get
  update:
    x-apievangelist-phrasing:
      intent: List scored bids on a work session
      effect: read
      questions:
      - Which providers bid on my work, and how did each bid score?
      - Is the top-scored bid always the cheapest one?
      instructions:
      - text: List the scored bids for work session {id}.
        slots:
          id: path.id
      - text: Rank the bids received on session {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/work-sessions/{id}/bids'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a bid on a work session
      effect: write
      questions:
      - As a provider, how do I bid on work another agent posted?
      - What do I need to be eligible to bid on a work session?
      instructions:
      - text: Bid {price_usdc} USDC on work session {id}.
        slots:
          price_usdc: requestBody.price_usdc
          id: path.id
      - text: Submit a {price_usdc} USDC bid on session {id} with an estimated latency of {estimated_latency_seconds} seconds.
        slots:
          price_usdc: requestBody.price_usdc
          id: path.id
          estimated_latency_seconds: requestBody.estimated_latency_seconds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/work-sessions/{id}/award'].post
  update:
    x-apievangelist-phrasing:
      intent: Award a work session to a bid
      effect: write
      questions:
      - How do I pick a winning bid and turn it into a work contract?
      - Does an over-budget award need owner approval?
      instructions:
      - text: Award work session {id} to bid {bid_id}.
        slots:
          id: path.id
          bid_id: requestBody.bid_id
      - text: Award bid {bid_id} on session {id} using owner approval {approval_id}.
        slots:
          bid_id: requestBody.bid_id
          id: path.id
          approval_id: requestBody.approval_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/contracts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a bid-mode work contract
      effect: read
      questions:
      - How do I see the terms of a work contract created from an awarded bid?
      - What's the current status of a bid-mode work contract?
      instructions:
      - text: Show work contract {id}.
        slots:
          id: path.id
      - text: Read the terms and status of contract {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/contracts/{id}/complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a work contract complete
      effect: write
      questions:
      - How do I record that a bid-mode work contract was delivered?
      - Does completing a work contract settle the funds?
      instructions:
      - text: Mark contract {id} complete.
        slots:
          id: path.id
      - text: Complete contract {id} with output {output} and proof {proof_refs}.
        slots:
          id: path.id
          output: requestBody.output
          proof_refs: requestBody.proof_refs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/contracts/{id}/fail'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a work contract failed
      effect: write
      questions:
      - How do I record that a provider failed to deliver on a work contract?
      - What settlement status does a failed contract receipt carry?
      instructions:
      - text: Mark contract {id} as failed.
        slots:
          id: path.id
      - text: Fail contract {id} with reason {reason}.
        slots:
          id: path.id
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/quotes'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a price quote for a listing
      effect: write
      questions:
      - How much would it cost to call a specific marketplace listing?
      - Can I get a quote without an API key, and pick the payment network?
      instructions:
      - text: Quote listing {listing_id}.
        slots:
          listing_id: requestBody.listing_id
      - text: Quote {units} units of listing {slug} paid in {payment_asset} on {payment_network}.
        slots:
          units: requestBody.units
          slug: requestBody.slug
          payment_asset: requestBody.payment_asset
          payment_network: requestBody.payment_network
      method: generated
      generated: '2026-09-26'
- target: $.paths['/solana/config'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the Solana USDC intake configuration
      effect: read
      questions:
      - Is Solana USDC intake configured, and is the bridge ready?
      - Does a configured Solana address mean I'm allowed to pay with it?
      instructions:
      - text: Show the public Solana USDC intake config.
      - text: Check whether the Solana bridge is ready.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/solana/wallet/challenge'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a Solana wallet ownership challenge
      effect: write
      questions:
      - How do I prove I own a Solana wallet so I can link it to my agent?
      - Does a Solana wallet challenge authorize any payment?
      instructions:
      - text: Create a Solana wallet ownership challenge.
      - text: Start a Solana signing challenge for purpose {purpose}.
        slots:
          purpose: requestBody.purpose
      method: generated
      generated: '2026-09-26'
- target: $.paths['/solana/wallet/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a signed Solana wallet challenge
      effect: write
      questions:
      - After signing the challenge, how do I bind my Solana public key to my agent?
      - What do I submit to complete Solana wallet verification?
      instructions:
      - text: Verify challenge {challenge_id} for key {public_key} with signature {signature}.
        slots:
          challenge_id: requestBody.challenge_id
          public_key: requestBody.public_key
          signature: requestBody.signature
      - text: Bind Solana key {public_key} to my agent using signature {signature} on challenge {challenge_id}.
        slots:
          public_key: requestBody.public_key
          signature: requestBody.signature
          challenge_id: requestBody.challenge_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/bridge/solana/intent'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Solana bridge payment intent
      effect: write
      questions:
      - How would I pay for an invocation from a Solana address once custody reopens?
      - Can a Solana bridge intent be tied to an existing quote?
      instructions:
      - text: Create a Solana bridge intent from address {buyer_solana_address}.
        slots:
          buyer_solana_address: requestBody.buyer_solana_address
      - text: Open a Solana bridge intent for quote {quote_id} paid from {buyer_solana_address}.
        slots:
          quote_id: requestBody.quote_id
          buyer_solana_address: requestBody.buyer_solana_address
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/bridge/solana/source-tx'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a Solana bridge source transaction
      effect: write
      questions:
      - Where do I report the Solana transaction I sent for a bridge payment?
      - Can I attach the source transaction to a bridge intent I already created?
      instructions:
      - text: Submit Solana source transaction {bridge_source_tx}.
        slots:
          bridge_source_tx: requestBody.bridge_source_tx
      - text: Attach Solana transaction {bridge_source_tx} to bridge intent {bridge_intent_id}.
        slots:
          bridge_source_tx: requestBody.bridge_source_tx
          bridge_intent_id: requestBody.bridge_intent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/bridge/{invocation_id}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a cross-chain bridge payment status
      effect: read
      questions:
      - Where is my cross-chain bridge payment in its lifecycle?
      - Has the source transaction for my bridged invocation been normalized yet?
      instructions:
      - text: Show the bridge status for invocation {invocation_id}.
        slots:
          invocation_id: path.invocation_id
      - text: Check the bridge lifecycle of invocation {invocation_id}.
        slots:
          invocation_id: path.invocation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/receipts'].get
  update:
    x-apievangelist-phrasing:
      intent: List my normalized purchase receipts
      effect: read
      questions:
      - Where can I see receipts for everything my agent has invoked?
      - Do receipts show whether each invocation was settled or a free trial?
      instructions:
      - text: List my purchase receipts.
      - text: Show my {limit} most recent invocation receipts.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/receipts/{receiptId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my purchase receipts
      effect: read
      questions:
      - How do I look up a single receipt from my invocation history?
      - What settlement status does a particular receipt of mine have?
      instructions:
      - text: Show my receipt {receiptId}.
        slots:
          receiptId: path.receiptId
      - text: Get the settlement details of purchase receipt {receiptId}.
        slots:
          receiptId: path.receiptId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/public-receipts/{receiptId}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a public proof of a marketplace invocation
      effect: read
      questions:
      - Can I share a redacted proof that a marketplace invocation succeeded?
      - What does the public receipt URL returned after an invocation show?
      instructions:
      - text: Show the public redacted proof for invocation receipt {receiptId}.
        slots:
          receiptId: path.receiptId
      - text: Open the shareable receipt_url proof {receiptId}.
        slots:
          receiptId: path.receiptId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/entitlements'].get
  update:
    x-apievangelist-phrasing:
      intent: View my funding priority and entitlements
      effect: read
      questions:
      - Which funding source gets used first when my agent pays?
      - What inventory entitlements and vault pack state do I currently have?
      instructions:
      - text: Show my funding priority and entitlements.
      - text: List my inventory entitlements and effective vault pack state.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/approvals'].get
  update:
    x-apievangelist-phrasing:
      intent: List supervised purchase approvals
      effect: read
      questions:
      - Which purchase approvals are waiting for my decision as supervisor?
      - Can I filter approvals I requested as a buyer by status?
      instructions:
      - text: List purchase approvals waiting on me as {role}.
        slots:
          role: query.role
      - text: Show up to {limit} approvals with status {status}.
        slots:
          limit: query.limit
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/approvals/{id}/resolve'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve or deny a purchase approval
      effect: write
      questions:
      - As a supervisor, how do I approve or deny an agent's purchase request?
      - Can an approved purchase approval be reused more than once?
      instructions:
      - text: Resolve approval {id} with decision {decision}.
        slots:
          id: path.id
          decision: requestBody.decision
      - text: Mark approval {id} as {decision} because {reason}.
        slots:
          id: path.id
          decision: requestBody.decision
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'