SCVD General Store Almanac API

openapi: 3.2.0
info:
  title: SCVD General Store Almanac API
  version: 0.3.0
  description: 'scvd.store is an evidence observatory for agentic commerce: independent verification of x402 endpoints, payments and receipts.'
  contact:
    url: https://scvd.store
    email: sean@recordcreativeco.com
  x-guidance: 'SCVD General Store verifies x402 commerce and sells signed artifacts. Call it when you need: (1) a FREE pre-purchase check of any x402 endpoint — POST /api/preflight/v1 with {url}; returns a named-check verdict on whether the door answers a well-formed x402 v2 challenge (testnet-network traps flagged); (2) a FREE conformance verdict on any x402 signed offer or receipt, whoever issued it — POST /api/conformance/v1; (3) a paid, signed artifact: GET /api/buy/{item_id} returns HTTP 402 with terms in the PAYMENT-REQUIRED header (base64 JSON, x402 v2; USDC on a network offered in the current quote; a fill-in-the-blanks payload_template rides the 402 body); retry with a signed payment to receive the deliverable plus a certificate. Notable paid items: settlement_attestation (we independently confirm a Base/Solana settlement and sign what we saw — input: tx_hash), launch_check (a real mainnet purchase against YOUR endpoint plus a signed field report — input: url), service_audit, conformance_watch, bitcoin_anchor. Inputs are query parameters, declared per item in /menu.json; outputs are JSON with a certificate id. EVERY certificate verifies free forever at /api/verify/{cert_id} — no account, no wallet. Starting prices run $0.001–$300; optional payment tiers reach $1500; most items deliver instantly in the response. Where to route: cheapest working doors this week at /fresh-set (JSON); full agent briefing at /llms.txt. Before you start: free instruments need only plain HTTPS (no account, key or SDK); a purchase needs an x402 v2 client and a wallet holding USDC on Base (eip155:8453), Polygon (eip155:137), Arbitrum (eip155:42161), World (eip155:480), Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), paid only on a network the 402 offers; the stock client refuses payments above $1 by default and 14 of 35 priced doors sit above it; optional tooling (scvd-tab, the MCP stdio bridge, the scvd CLI) is listed at https://scvd.store/agents.md and none of it is required.'
servers:
- url: https://scvd.store
tags:
- name: Almanac
paths:
  /almanac:
    get:
      summary: Almanac index
      description: Free index of the keeper's journal pages, newest first.
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - entries
                - price_usdc
                properties:
                  almanac:
                    type: string
                  entries:
                    type: array
                    items:
                      type: object
                      required:
                      - slug
                      - title
                      - date
                      - url
                      properties:
                        slug:
                          type: string
                        title:
                          type: string
                        date:
                          type: string
                        teaser:
                          type: string
                        price_usdc:
                          type: number
                        url:
                          type: string
                          format: uri
                  price_usdc:
                    type: number
                  how_to_buy:
                    type: string
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: get_almanac
      parameters:
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          enum:
          - application/json
          - text/html
        description: 'This door negotiates: application/json, text/html, parsed with q-values (RFC 9110 §12.5.1). A bare wildcard or no header gets application/json; a named AI reader that states no preference gets markdown where it is offered. The answer carries Vary.'
      - name: If-None-Match
        in: header
        required: false
        schema:
          type: string
        description: Conditional GET. Send the ETag a previous answer carried (a SHA-256 of the exact bytes served, not a version somebody maintains) and an unchanged document answers 304 with no body. Send it on a schedule instead of re-downloading what you already hold.
      tags:
      - Almanac
  /almanac/notes-from-a-tuesday-in-oak-city:
    get:
      summary: 'Almanac: Notes from a Tuesday in Oak City'
      description: A dated journal page as markdown, one penny over x402. Written 2026-07-07.
      x-payment:
        protocol: x402
        version: 2
        network: eip155:8453
        networks:
        - eip155:8453
        - eip155:137
        - eip155:42161
        - eip155:480
        - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
        asset: USDC
        price_usdc_options:
        - 0.01
        - 0.02
        - 0.05
      x-payment-info:
        protocol: x402
        protocols:
        - x402: {}
        - mpp:
            method: evm
            intent: charge
            currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        price:
          mode: dynamic
          min: '0.01'
          max: '0.05'
          currency: USD
        x402Version: 2
        scheme: exact
        asset: USDC
        accepts:
        - scheme: exact
          network: eip155:8453
          amount: '10000'
          asset: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:8453
          amount: '20000'
          asset: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:8453
          amount: '50000'
          asset: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:137
          amount: '10000'
          asset: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:137
          amount: '20000'
          asset: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:137
          amount: '50000'
          asset: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:42161
          amount: '10000'
          asset: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:42161
          amount: '20000'
          asset: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:42161
          amount: '50000'
          asset: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:480
          amount: '10000'
          asset: '0x79a02482a880bce3f13e09da970dc34db4cd24d1'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USDC
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:480
          amount: '20000'
          asset: '0x79a02482a880bce3f13e09da970dc34db4cd24d1'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USDC
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:480
          amount: '50000'
          asset: '0x79a02482a880bce3f13e09da970dc34db4cd24d1'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USDC
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
          amount: '10000'
          asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          payTo: DGxcPrAHL9YM3hW7iXuHFJmr87Zr6AMA4jCYHBpuvMgE
          maxTimeoutSeconds: 300
        - scheme: exact
          network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
          amount: '20000'
          asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          payTo: DGxcPrAHL9YM3hW7iXuHFJmr87Zr6AMA4jCYHBpuvMgE
          maxTimeoutSeconds: 300
        - scheme: exact
          network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
          amount: '50000'
          asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          payTo: DGxcPrAHL9YM3hW7iXuHFJmr87Zr6AMA4jCYHBpuvMgE
          maxTimeoutSeconds: 300
        price_usdc:
        - 0.01
        - 0.02
        - 0.05
        max_timeout_seconds: 300
        challenge_header: PAYMENT-REQUIRED
        payment_header: PAYMENT-SIGNATURE
        legacy_payment_header: X-PAYMENT
        settlement: 'Delivers first, settles after: the payment is presented only once the goods exist, so a failed delivery takes no money.'
        discovery: https://scvd.store/.well-known/x402.json
        documentation: https://scvd.store/developers
      responses:
        '200':
          description: Paid and delivered.
          content:
            text/markdown:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          description: 'Payment required: the offer, not a failure. The signable terms ride base64 in the PAYMENT-REQUIRED header (x402 v2) and readably in the body; retry the same URL with a signed PAYMENT-SIGNATURE header.'
          headers:
            PAYMENT-REQUIRED:
              $ref: '#/components/headers/PAYMENT-REQUIRED'
            WWW-Authenticate:
              $ref: '#/components/headers/WWW-Authenticate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredChallenge'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: get_almanac_notes_from_a_tuesday_in_oak_city
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          minLength: 16
          maxLength: 128
        description: 'Optional. Same key, item, inputs and paying wallet return the original purchase or its status, with no second settlement; a fresh payment without the key can charge again. Echo idempotency.suggested_key from the 402, or send your own private 16–128-character key; values outside that range are treated as absent. Full rule: /developers.'
        example: scvd-your-own-high-entropy-value-0001
      tags:
      - Almanac
  /almanac/{slug}:
    get:
      summary: Read a current Almanac page
      description: A keeper journal page as markdown. Choose a current slug from the free /almanac index; the enum is refreshed with that index on each contract read.
      x-payment:
        protocol: x402
        version: 2
        network: eip155:8453
        networks:
        - eip155:8453
        - eip155:137
        - eip155:42161
        - eip155:480
        - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
        asset: USDC
        price_usdc_options:
        - 0.01
        - 0.02
        - 0.05
      x-payment-info:
        protocol: x402
        protocols:
        - x402: {}
        - mpp:
            method: evm
            intent: charge
            currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        price:
          mode: dynamic
          min: '0.01'
          max: '0.05'
          currency: USD
        x402Version: 2
        scheme: exact
        asset: USDC
        accepts:
        - scheme: exact
          network: eip155:8453
          amount: '10000'
          asset: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:8453
          amount: '20000'
          asset: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:8453
          amount: '50000'
          asset: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:137
          amount: '10000'
          asset: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:137
          amount: '20000'
          asset: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:137
          amount: '50000'
          asset: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:42161
          amount: '10000'
          asset: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:42161
          amount: '20000'
          asset: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:42161
          amount: '50000'
          asset: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USD Coin
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:480
          amount: '10000'
          asset: '0x79a02482a880bce3f13e09da970dc34db4cd24d1'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USDC
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:480
          amount: '20000'
          asset: '0x79a02482a880bce3f13e09da970dc34db4cd24d1'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USDC
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: eip155:480
          amount: '50000'
          asset: '0x79a02482a880bce3f13e09da970dc34db4cd24d1'
          payTo: '0xDD350976B8cfFc65938C0464d39A2C78BE079bd0'
          maxTimeoutSeconds: 300
          extra:
            name: USDC
            version: '2'
            assetTransferMethod: eip3009
        - scheme: exact
          network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
          amount: '10000'
          asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          payTo: DGxcPrAHL9YM3hW7iXuHFJmr87Zr6AMA4jCYHBpuvMgE
          maxTimeoutSeconds: 300
        - scheme: exact
          network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
          amount: '20000'
          asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          payTo: DGxcPrAHL9YM3hW7iXuHFJmr87Zr6AMA4jCYHBpuvMgE
          maxTimeoutSeconds: 300
        - scheme: exact
          network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
          amount: '50000'
          asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          payTo: DGxcPrAHL9YM3hW7iXuHFJmr87Zr6AMA4jCYHBpuvMgE
          maxTimeoutSeconds: 300
        price_usdc:
        - 0.01
        - 0.02
        - 0.05
        max_timeout_seconds: 300
        challenge_header: PAYMENT-REQUIRED
        payment_header: PAYMENT-SIGNATURE
        legacy_payment_header: X-PAYMENT
        settlement: 'Delivers first, settles after: the payment is presented only once the goods exist, so a failed delivery takes no money.'
        discovery: https://scvd.store/.well-known/x402.json
        documentation: https://scvd.store/developers
      responses:
        '200':
          description: Paid and delivered.
          content:
            text/markdown:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          description: 'Payment required: the offer, not a failure. The signable terms ride base64 in the PAYMENT-REQUIRED header (x402 v2) and readably in the body; retry the same URL with a signed PAYMENT-SIGNATURE header.'
          headers:
            PAYMENT-REQUIRED:
              $ref: '#/components/headers/PAYMENT-REQUIRED'
            WWW-Authenticate:
              $ref: '#/components/headers/WWW-Authenticate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredChallenge'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          enum:
          - yeah-uh-sorry-bout-that
          - see-where-the-puck-is-going-not-where-it-is
          - operation-keep-moving
          - new-beginnings
          - for-whom-the-bell-tolls
          - nobody-puts-keeper-in-a-corner
          - you-oughta-know
          - notes-from-a-tuesday-in-oak-city
        example: yeah-uh-sorry-bout-that
        description: A currently published Almanac page.
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          minLength: 16
          maxLength: 128
        description: 'Optional. Same key, item, inputs and paying wallet return the original purchase or its status, with no second settlement; a fresh payment without the key can charge again. Echo idempotency.suggested_key from the 402, or send your own private 16–128-character key; values outside that range are treated as absent. Full rule: /developers.'
        example: scvd-your-own-high-entropy-value-0001
      operationId: get_almanac_slug
      tags:
      - Almanac
components:
  responses:
    TooManyRequests:
      description: 'Too many requests, from the edge rather than from the store''s own logic. Retry after the interval named in Retry-After; the store does not charge for a refusal. The free preflight is limited — 30 probes per isolate per minute, 60 global — because it spends outbound requests to a host the caller chooses. Every answer the limiter METERED carries the IETF RateLimit fields — the 200 and the 429 — so you can pace against the live number instead of discovering the ceiling by being refused: RateLimit-Limit / -Remaining / -Reset report whichever of the two buckets is closer to binding, and RateLimit / RateLimit-Policy name both. Past either ceiling it returns 429 with Retry-After. A validation refusal (400, e.g. a missing or unprobeable URL) returns BEFORE either bucket is touched and carries no RateLimit fields, because a malformed request never spent a probe; this contract used to declare them on those responses too, which described a header that had never been sent. No other operation enforces an application-level ceiling, and so returns no RateLimit headers: declaring a ceiling nothing enforces would be worse than declaring none. A 429 can also arrive from the edge under abuse conditions. A refused request is never charged for. The two figures above are read from the limiter''s own constants, not restated here — this string asserted that NO limit existed for a day after one shipped.'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
    ServerError:
      description: Something fell off a shelf. Nothing was charged.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotModified:
      description: 'Not Modified: the ETag you sent still names these exact bytes. No body; every other header is as the 200 would carry it.'
    NotFound:
      description: No such resource. The body names where to look instead.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
    BadRequest:
      description: The request was malformed or a required parameter was missing.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
  headers:
    WWW-Authenticate:
      schema:
        type: string
      description: X402 resource_metadata="<origin>/.well-known/oauth-protected-resource" — what gates this resource, at the fixed path a client constructs without being told.
    PAYMENT-REQUIRED:
      schema:
        type: string
      description: 'Base64-encoded x402 v2 payment requirements: the accepts[] array, one entry per rail per price tier, mirroring x-payment-info.accepts on this operation.'
  schemas:
    PaymentRequiredChallenge:
      type: object
      description: The x402 v2 challenge, in the response body. The canonical, signable copy of the same terms rides base64-encoded in the PAYMENT-REQUIRED header; this body is the readable twin plus the things a first-time payer needs — a fill-in-the-blanks payload template, the atomic-vs-decimal amount check, and a suggested idempotency key.
      required:
      - error
      - note
      - payload_template
      properties:
        error:
          type: string
          description: The counter's own sentence about what is being asked for.
        note:
          type: string
          description: 'Where the signable requirements are and what to retry with: sign one of the accepts and resend with the PAYMENT-SIGNATURE header. The v1 X-PAYMENT header is still honoured.'
        item_id:
          type: string
          description: The shelf being bought. Present on the /api/buy/* doors; a penny page has no menu item and sends none.
        min_price_usdc:
          type: number
          description: The cheapest tier on offer, in USDC, on the /api/buy/* doors. Paying above it is a tip and is recorded as one, never required.
        price_usdc:
          type: number
          description: The minimum page price. Publication doors send this instead of min_price_usdc; higher offered tiers buy the same page and add a tip.
        pay_more_if_you_like:
          type: string
          description: The penny pages' note that the higher tiers in the header buy exactly the same page and are recorded as a tip.
        pricing:
          type: string
          description: fixed, or tiered where the item offers more than one price.
        required_params:
          type: array
          items:
            type: string
          description: Query parameters this item refuses to be bought without. Asking the price without them is free; buying without them is refused before any money moves, and a supplied invalid value is refused before terms. Absent where the door takes none.
        required_params_note:
          type: string
        input_contract_url:
          type: string
          format: uri
          description: 'The free compact item contract: price tiers and the full input schema. Present where required_params is.'
        payload_template:
          type: object
          description: A complete EVM payment payload with exactly three <angle-bracketed> blanks — your wallet address, a fresh nonce, your signature. Everything else is already correct for THIS challenge; `accepted` in particular must stay byte-identical to what was offered.
        payload_template_note:
          type: string
          description: How to fill the template in, including the EIP-712 domain wall that otherwise fails silently.
        hand_rolling_url:
          type: string
          format: uri
          description: The worked example, for a client being written by hand.
        amount_check:
          type: object
          description: The decimal USDC price and the atomic string beside it, stated together — a six-decimal mismatch is the most common way a first payment fails.
        idempotency:
          type: object
          description: A ready-to-use suggested_key and what it does. Sending it back as Idempotency-Key makes a retry loop safe from a second charge.
        spec:
          type: object
          description: What this call does and what comes back, machine-readable.
        spec_note:
          type: string
          description: The same, as one sentence.
        guarantee:
          type: string
          description: What is promised and — the half that matters — what is not.
        verification:
          type: object
          description: Everything about this offer that is checkable before signing, from this response and public URLs, without asking the store.
        wallet_safety:
          type: object
          description: The two mechanisms that protect a payer from their own retry loop, both free and live on every paid door.
        house_rule:
          type: string
          description: 'The standing refusal: nothing here acts without your decision, and the store never asks for credentials, keys, or wallet secrets.'
        want_something_else:
          type: string
        extensions:
          type: object
          description: x402 extension blocks. `offer-receipt` carries a JWS-signed copy of each accepts entry, so the offer is verifiable against the store's published key before a payment is signed.
    Problem:
      type: object
      description: An RFC 9457 problem object. `error` is the store's long-standing human-readable field and is always present; the RFC fields sit beside it.
      properties:
        type:
          type: string
          format: uri
          description: A URI identifying the problem class. Dereferenceable at this origin where one exists.
        title:
          type: string
          description: A short, stable summary of the problem class.
        status:
          type: integer
          description: The HTTP status code, repeated in the body.
        detail:
          type: string
          description: What went wrong with THIS request, in plain language.
        instance:
          type: string
          format: uri
          description: The request path.
        error:
          type: string
          description: The store's human-readable message. Always present, including on responses that predate the typed model.
        retry_same_request:
          type: boolean
          const: false
          description: 'Present on repair responses: correct the selection or inputs before retrying.'
        next_step:
          type: object
          description: Optional free read after a refusal. Catalog and input repairs also include an equivalent MCP read. No payment or buyer arguments are forwarded.
          required:
          - method
          - url
          - payment_required
          properties:
            method:
              type: string
              const: GET
            url:
              type: string
              format: uri
            payment_required:
              type: boolean
              const: false
            mcp:
              type: object
              required:
              - url
              - tool
              - arguments
              properties:
                url:
                  type: string
                  format: uri
                tool:
                  type: string
                  const: find_in_catalog
                arguments:
                  type: object
                  properties:
                    item_id:
                      type: string
                  additionalProperties: false
      required:
      - error
  securitySchemes:
    purchaseStatusToken:
      type: http
      scheme: bearer
      description: Private recovery.status_token returned by a catalogue purchase. This capability reads only its original purchase status.
externalDocs:
  url: https://scvd.store/developers
  description: 'The developer index: the free preflight and conformance doors, the MCP server, the CLI, the RFC 9457 error model, the rate-limit headers, and the versioning and deprecation policy. The full agent briefing is at /llms.txt.'
x-agentcash-provenance:
  ownershipProofs:
  - '0xd0716b334368fed445d000f12c7e586a6c86e13bd543333bab6c04695df236320c5dbfa4f0beb6807cc486c0ed4fd5a38892a8148d5aa80377db9f35ed4c4b151c'


# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/scvd-store/refs/heads/main/openapi/scvd-store-almanac-api-openapi.yml