config.example.yaml

# ---------------------------------------------------------------------------
# Agent Commerce Gateway - example configuration
#
# Copy to `config.yaml` and edit, or generate one with:
#   npm run agent-commerce -- init
#
# Validate it with:
#   npm run agent-commerce -- validate
#
# `${VAR}` placeholders are resolved from the environment at load time. An
# unresolved one fails startup, and config errors never print a resolved value.
# ---------------------------------------------------------------------------

version: 1

merchant:
  id: demo-store
  name: Demo Data Store
  publicBaseUrl: ${GATEWAY_PUBLIC_BASE_URL}

server:
  port: ${GATEWAY_PORT}
  host: 0.0.0.0

  # Required to serve the operator routes (/api/receipts, /api/events). If
  # unset they return 404 rather than serving the merchant's commerce ledger
  # openly. Use a real secret in any deployment reachable by anyone else.
  adminToken: ${ADMIN_TOKEN}

  # Browser origins permitted to read the gateway. Empty (the default) means
  # none. Agent traffic needs no entry here.
  allowedOrigins:
    - ${DASHBOARD_ORIGIN}

storage:
  receipts:
    driver: sqlite
    path: ${RECEIPT_STORE_PATH}

protocols:
  http:
    enabled: true
  mcp:
    enabled: true
    mountPath: /mcp
  # A2A (Agent2Agent) v1.0.0 - experimental, off by default.
  # Enabling it serves JSON-RPC `SendMessage` at mountPath and the
  # specification-fixed Agent Card at /.well-known/agent-card.json. Clients must
  # send `A2A-Version: 1.0`. Streaming, task persistence and push notifications
  # are not implemented; see docs/protocols.md#a2a.
  a2a:
    enabled: false
    mountPath: /a2a
  # ACP (Agentic Commerce Protocol), stable snapshot 2026-04-17 - experimental,
  # off by default. Enabling it serves the five checkout routes under mountPath
  # and the specification-fixed discovery document at /.well-known/acp.json.
  # Every checkout call needs `Authorization: Bearer <token>` and
  # `API-Version: 2026-04-17`; a POST also needs an `Idempotency-Key`. Only the
  # `checkout` service is served: carts, feed, orders, delegated payment and authentication, webhooks
  # and the ACP MCP binding are not implemented.
  #
  # Enabling it needs the five mapped resources too - a complete, validating
  # config is in examples/acp-checkout/. See docs/protocols.md#acp.
  acp:
    enabled: false
    mountPath: /acp

resources:
  # --- free resource: exposes a merchant API endpoint -----------------------
  weather_basic:
    name: Basic Weather
    description: Current basic weather for a city. Free.
    input:
      type: object
      properties:
        city:
          type: string
          description: City name, e.g. "Berlin"
      required: [city]
      additionalProperties: false
    backend:
      type: http
      method: GET
      url: ${MERCHANT_API_BASE_URL}/api/weather/{city}
      timeoutMs: 5000
    pricing:
      type: free
    expose: [http, mcp]

  # --- paid resource: requires x402 settlement ------------------------------
  market_report:
    name: Premium Market Report
    description: Latest premium market analysis. Paid resource.
    input:
      type: object
      properties: {}
      additionalProperties: false
    backend:
      type: http
      method: GET
      url: ${MERCHANT_API_BASE_URL}/api/report
      timeoutMs: 10000
    pricing:
      type: fixed
      amount: "0.01"
      currency: USDC
    expose: [http, mcp]
    payments: [x402]

payments:
  x402:
    enabled: true
    network: ${X402_NETWORK}
    rpcUrl: ${X402_RPC_URL}
    asset: ${X402_ASSET}
    assetName: ${X402_ASSET_NAME}
    assetVersion: ${X402_ASSET_VERSION}
    assetDecimals: ${X402_ASSET_DECIMALS}
    # Merchant-controlled settlement destination.
    # This is NEVER a gateway-owned wallet - see docs/security.md.
    payTo: ${MERCHANT_WALLET}
    # Seconds a payment challenge stays valid
    maxTimeoutSeconds: 120
    # Who verifies the authorization and broadcasts the transfer.
    #
    # mode: local   the facilitator runs in this process and signs with
    #               signerPrivateKey. Meant for the local dev chain. Refused
    #               on mainnet, and a well-known Anvil key is refused against
    #               any RPC that is not local or private.
    #
    # mode: remote  an HTTP facilitator does the signing; this gateway holds no
    #               signing key. Requires https, except on a local or private
    #               host off mainnet, and on mainnet a credential unless
    #               allowUnauthenticatedFacilitator is set.
    facilitator:
      mode: local
      signerPrivateKey: ${X402_FACILITATOR_PRIVATE_KEY}
    #
    # A public testnet instead - no key anywhere in this file:
    #
    # network: eip155:84532
    # facilitator:
    #   mode: remote
    #   url: https://x402.org/facilitator
    #   auth:
    #     type: none
    #
    # Base mainnet. None of these are defaults. `auth` is required unless the
    # facilitator takes no credential and allowUnauthenticatedFacilitator: true
    # is set instead:
    #
    # network: eip155:8453
    # asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"  # USDC on Base
    # assetName: "USD Coin"  # the EIP-712 domain name, not "USDC"
    # allowMainnet: true
    # facilitator:
    #   mode: remote
    #   url: ${X402_FACILITATOR_URL}
    #   auth:
    #     type: bearer
    #     token: ${X402_FACILITATOR_TOKEN}

  # MPP (charge, evm, EIP-3009) is experimental and disabled by default. It
  # settles through an x402 facilitator and can reuse the local values above.
  # MPP resources use USDC; [x402, mpp] selects the first enabled rail.
  #
  # mpp:
  #   enabled: true
  #   rpcUrl: ${X402_RPC_URL}
  #   asset: ${X402_ASSET}
  #   assetName: ${X402_ASSET_NAME}
  #   assetVersion: ${X402_ASSET_VERSION}
  #   recipient: ${MERCHANT_WALLET}
  #   realm: localhost
  #   challengeSecret: ${MPP_CHALLENGE_SECRET} # at least 32 characters
  #   facilitator:
  #     mode: local
  #     signerPrivateKey: ${X402_FACILITATOR_PRIVATE_KEY}

# ---------------------------------------------------------------------------
# AP2 mandate verification - experimental, off by default.
#
# Makes a paid resource require proof that the human behind the agent approved
# THIS purchase: a signed AP2 v0.2.0 Direct Checkout Mandate, verified before
# the payment is allowed to settle. A mandate never unlocks a resource on its
# own and never moves money; the resource still takes a real payment.
#
# Public keys only, written here by you. Nothing is fetched at runtime: no
# JWKS, no `jku`, no `x5u`, no issuer discovery. Rotate by listing the new key
# beside the old one, moving the signer to the new `kid`, then removing the old.
#
# Needs the optional peers:  npm install jose @sd-jwt/core canonicalize
# Full reference: docs/ap2.md
# ---------------------------------------------------------------------------
# authorization:
#   ap2:
#     enabled: true
#     specVersion: "0.2.0"     # the only supported value
#     mode: direct             # the only supported mode
#     clockSkewSeconds: 60     # default; 300 is the ceiling
#     replay:
#       # Its own file. An authorization replay is not a payment replay, and a
#       # spent mandate must stay spent for as long as you can be asked what
#       # you delivered.
#       path: ./data/ap2-authorizations.sqlite
#     trust:
#       # Who may issue a Checkout Mandate. Usually the buyer's shopping agent
#       # or credential provider.
#       mandateIssuers:
#         - issuer: https://surface.example
#           audience: merchant.example    # required: who the mandate is for
#           keys:
#             - kid: mandate-2026-01
#               jwk: { kty: EC, crv: P-256, x: "...", y: "..." }
#       # Who signs YOUR checkout documents. A separate list on purpose:
#       # signing checkouts must not confer the power to issue mandates.
#       checkoutIssuers:
#         - issuer: https://merchant.example
#           audience: agent-commerce
#           keys:
#             - kid: checkout-2026-01
#               jwk: { kty: EC, crv: P-256, x: "...", y: "..." }
#
# Then require it on a paid resource, under `resources:`:
#
#   market_report:
#     pricing: { type: fixed, amount: "0.01", currency: USDC }
#     payments: [x402]
#     authorization:
#       required: [ap2]