# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Thehiveryiq Com X402 API
  version: 1.0.0
extends: openapi/thehiveryiq-com-x402-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: 20
- target: $.paths['/v1/x402'].get
  update:
    x-apievangelist-phrasing:
      intent: Get x402 facilitator metadata
      effect: read
      questions:
      - Which settlement schemes and chain/asset combinations does the HiveMorph x402 facilitator support?
      - What recipient address does the x402 facilitator settle payments to?
      instructions:
      - text: Show me the x402 facilitator metadata, including supported schemes and recipient address.
      - text: Fetch the facilitator overview with its pointer to per-rail discovery.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/pricing'].get
  update:
    x-apievangelist-phrasing:
      intent: View the x402 per-call pricing table
      effect: read
      questions:
      - How much does each monetized endpoint cost per call in USD?
      - Which pricing tier is each paid endpoint assigned to?
      instructions:
      - text: List every monetized endpoint with its tier and per-call USD price.
      - text: Pull the current x402 pricing table.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get x402 call and revenue statistics
      effect: read
      questions:
      - How many 402 payment challenges have been issued and how many calls were actually paid?
      - What is the total paid revenue settled so far and which endpoints are called most?
      instructions:
      - text: Show aggregate x402 call statistics with revenue and top endpoints.
      - text: Report total calls served versus paid passes across all endpoints.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/stats/buckets'].get
  update:
    x-apievangelist-phrasing:
      intent: Get endpoint stats grouped into buckets
      effect: read
      questions:
      - Can I see call counters rolled up by category like Receipts, Compliance and Energy?
      - Which high-level bucket of endpoints gets the most traffic?
      instructions:
      - text: Show the bucketed endpoint stats with drill-down endpoints per bucket.
      - text: Break down call counters by the eleven top-level endpoint categories.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/proof/submit'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit an on-chain payment proof for a 402
      effect: write
      questions:
      - How do I turn a paid 402 nonce into an access token for the X-Hive-Access header?
      - What happens if I submit a fake transaction hash as payment proof?
      - Is the payment proof validated against the chain before an access token is issued?
      instructions:
      - text: Submit payment proof for nonce {nonce} with transaction {tx_hash} from payer {payer} on {chain}.
        slots:
          nonce: requestBody.nonce
          tx_hash: requestBody.tx_hash
          payer: requestBody.payer
          chain: requestBody.chain
      - text: Prove payment of nonce {nonce} using {asset} tx {tx_hash} on {chain} paid by {payer}.
        slots:
          nonce: requestBody.nonce
          asset: requestBody.asset
          tx_hash: requestBody.tx_hash
          chain: requestBody.chain
          payer: requestBody.payer
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/proof/verify'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether an x402 access token is valid
      effect: read
      questions:
      - Is my x402 access token still valid or has its 5-minute window expired?
      - Can I confirm an access token issued after payment before reusing it?
      instructions:
      - text: Verify access token {token} is still valid.
        slots:
          token: query.token
      - text: Check whether paid-access token {token} has expired.
        slots:
          token: query.token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/pricing/set'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the price for an endpoint (admin)
      effect: write
      questions:
      - As an admin, can I change the per-call price of a specific path?
      - Are pricing changes made through the admin endpoint persisted across restarts?
      instructions:
      - text: Set the price of path {path} to {amount} USD.
        slots:
          path: requestBody.path
          amount: requestBody.amount
      - text: Reprice {path} at {amount} USD in tier {tier}.
        slots:
          path: requestBody.path
          amount: requestBody.amount
          tier: requestBody.tier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/rails'].get
  update:
    x-apievangelist-phrasing:
      intent: List accepted x402 settlement rails
      effect: read
      questions:
      - Which chain and asset rails are accepted for x402 settlement?
      - What token contract and decimals does a paying agent need for the default rail?
      instructions:
      - text: List the available settlement rails and the current default rail.
      - text: Get contract and decimals metadata for each accepted payment rail.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/rails/select'].post
  update:
    x-apievangelist-phrasing:
      intent: Change the default settlement asset (admin)
      effect: write
      questions:
      - Can I switch the advertised default settlement asset from USDC to USDT?
      - Does changing the default rail remove other assets from 402 responses?
      instructions:
      - text: Make {asset} the default settlement asset.
        slots:
          asset: requestBody.asset
      - text: Switch the advertised default rail to {asset}.
        slots:
          asset: requestBody.asset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/stats/by-payer'].get
  update:
    x-apievangelist-phrasing:
      intent: Get x402 stats per payer (internal)
      effect: read
      questions:
      - Which payer addresses or DIDs make the most paid calls?
      - Can I see a payer's first and last seen time and referrer DID?
      instructions:
      - text: Show the top payers by paid call volume for path {path}.
        slots:
          path: query.path
      - text: List per-payer revenue forensics for the last {since_minutes} minutes.
        slots:
          since_minutes: query.since_minutes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/today'].get
  update:
    x-apievangelist-phrasing:
      intent: Get today's x402 quote and payment totals
      effect: read
      questions:
      - What were the quote and payment totals for a given UTC day?
      - How does actual revenue compare to the asking-price equivalent today?
      instructions:
      - text: Show today's UTC x402 aggregate including barter spread.
      - text: Get the daily x402 aggregate for {date}.
        slots:
          date: query.date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/barter'].get
  update:
    x-apievangelist-phrasing:
      intent: View counter-offer barter telemetry
      effect: read
      questions:
      - What share of paid calls were accepted at the floor price per path?
      - Can I see a histogram of amounts agents actually paid under the counter-offer scheme?
      instructions:
      - text: Show the barter demand-curve histogram for {date}.
        slots:
          date: query.date
      - text: Get counter-offer telemetry with {bucket_usd} USD histogram buckets.
        slots:
          bucket_usd: query.bucket_usd
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/failed'].get
  update:
    x-apievangelist-phrasing:
      intent: List unpaid or failed x402 nonces
      effect: read
      questions:
      - Which quoted nonces were never paid or had proofs that failed verification?
      - Where can I find the failed-transaction recovery queue?
      instructions:
      - text: List failed and unpaid nonces since {since}.
        slots:
          since: query.since
      - text: Show the failed-tx recovery queue.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/recover'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-verify a previously failed payment proof
      effect: write
      questions:
      - My transaction confirmed after the proof was rejected — can I get it re-checked?
      - Do replay and expiry rules still apply when recovering a failed proof?
      instructions:
      - text: Re-verify failed nonce {nonce} against transaction {tx_hash}.
        slots:
          nonce: requestBody.nonce
          tx_hash: requestBody.tx_hash
      - text: Recover the proof for nonce {nonce} with tx {tx_hash} on {chain}.
        slots:
          nonce: requestBody.nonce
          tx_hash: requestBody.tx_hash
          chain: requestBody.chain
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/bogo'].get
  update:
    x-apievangelist-phrasing:
      intent: See first-call-free redemptions
      effect: read
      questions:
      - How many agents have redeemed their free first call per endpoint family?
      - Which endpoint families are covered by the first-call-free offer?
      instructions:
      - text: Show the BOGO first-call-free redemption table.
      - text: List endpoint families eligible for a free first call.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/quote'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a signed x402 USDC payment quote
      effect: write
      questions:
      - Can I get a signed, redeemable USDC quote on Base for a specific endpoint?
      - What is required to request a post-quantum receipt profile on a quote?
      - Does the quote come with an ERC-681 deeplink a wallet can pay?
      instructions:
      - text: Quote a payment for endpoint {endpoint_path} as agent {agent_did}.
        slots:
          endpoint_path: requestBody.endpoint_path
          agent_did: requestBody.agent_did
      - text: Create an x402 quote for {amount_usdc} USDC with receipt profile {receipt_profile}.
        slots:
          amount_usdc: requestBody.amount_usdc
          receipt_profile: requestBody.receipt_profile
      - text: Issue a pq quote using delegation envelope {regulated_envelope_jti}.
        slots:
          regulated_envelope_jti: requestBody.regulated_envelope_jti
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/client-intent'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a browser-ready x402 payment intent
      effect: write
      questions:
      - Can a browser wallet fetch the amount, recipient and nonce it needs to pay via a simple GET?
      - Which receipt profiles can a client payment intent use without a delegation envelope?
      instructions:
      - text: Fetch a client payment intent for {endpoint_path} with profile {profile}.
        slots:
          endpoint_path: query.endpoint_path
          profile: query.profile
      - text: Get a client-intent GET for {amount_usdc} USDC.
        slots:
          amount_usdc: query.amount_usdc
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/client-intent'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a browser-ready payment intent via POST
      effect: write
      questions:
      - Is there a POST form of the client payment intent for wallets?
      - Can my frontend POST to get a live nonce and the proof-submission shape?
      instructions:
      - text: POST a new client payment intent and return the live nonce.
      - text: Create a client-intent via POST for my wallet checkout.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/wallet-intent'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a payment intent via the wallet-intent alias
      effect: write
      questions:
      - Does the wallet-intent GET path return the same data as client-intent?
      - Can a wallet call the wallet-intent alias with a profile and amount?
      instructions:
      - text: Call the wallet-intent alias for {endpoint_path} using profile {profile}.
        slots:
          endpoint_path: query.endpoint_path
          profile: query.profile
      - text: Get a wallet-intent for {amount_usdc} USDC.
        slots:
          amount_usdc: query.amount_usdc
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/x402/wallet-intent'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a payment intent via the wallet-intent POST alias
      effect: write
      questions:
      - Is there a POST wallet-intent alias for wallets that prefer POST?
      - What does POSTing to the wallet-intent alias give back?
      instructions:
      - text: POST to the wallet-intent alias to register a payment nonce.
      - text: Create a wallet-intent through the POST alias.
      method: generated
      generated: '2026-09-26'