generated: '2026-09-19'
method: derived
source: openapi/merchant-0-com-openapi.json
docs:
- https://merchant-0.com/.well-known/agent-card.json
summary: >-
  Derived from the 28 component schemas (all request bodies — the contract declares no response schemas
  beyond untyped objects), the path parameters, the query parameters and the descriptions. Two roots: the
  BUYER AGENT, identified by its DID (buyer_did, never returned raw — every read returns buyer_did_hash), and
  the CATALOG ITEM, identified by sku. A purchase is a CONTRACT (contract_id) that moves PENDING -> SIGNED ->
  EXECUTED and yields an EXECUTION (execution_id) with a deliverable, an INVOICE and a SETTLEMENT record; a
  legacy parallel path models the same thing as INTENT (intent_id) -> CART (cart_id). Subscriptions, trial
  grants, disputes, strategist reviews and referral codes hang off the buyer or the contract. There are no
  $ref links between schemas — the graph is by id field and resolved with follow-up GETs; there is no
  expansion parameter.
id_style:
  format: opaque strings; SKUs are human-readable slugs
  prefixes:
  - {entity: BuyerAgent, example: 'did:web:<domain>', source: 'AP2NegotiateBody description ("did:web:...")'}
  - {entity: CatalogItem (service), example: 'merchant0-intel-001', source: 'GET /api/catalog'}
  - {entity: CatalogItem (MRO product), example: 'MRO-FAST-DIN912-M8', source: 'GET /api/ucp/catalog/search'}
  - {entity: SubscriptionPlan, example: 'merchant0-intel-sub-monthly', source: 'agent card subscription_plans[].sku'}
  - {entity: Contract / Execution / Invoice / Dispute / Trial, example: 'opaque; format not published'}
entities:
- name: BuyerAgent
  description: The purchasing agent, identified by a did:web DID it asserts in request bodies. Carries a Diplomat reputation (may be FLAGGED), a lifetime_queries count and at most one active subscription per plan.
  schemas: []
  key: buyer_did (input) / buyer_did_hash (output)
  relationships:
  - {has_many: Contract, via: buyer_did}
  - {has_many: Intent, via: buyer_did}
  - {has_many: Subscription, via: buyer_did / subscriber_did}
  - {has_one: TrialGrant, via: buyer_did, note: one per DID}
  - {has_many: Dispute, via: buyer_did}
  - {has_one: ReferralCode, via: subscriber_did}
  - {has_one: DiplomatReputation, via: buyer_did, note: 'reset by diplomat_reputation_reset (operator)'}
- name: CatalogItem
  description: A priced offering. Two catalogs share the sku key space — the A2A service catalog (GET /api/catalog, 16 rows, category intelligence|data|commerce|agent|analysis|attestation|verification) and the MRO physical-goods catalog (GET /api/ucp/catalog/search, categories fasteners|sensors|safety|electrical|pneumatics). The inventory-check alias "resolves CEO catalog first, then MCP".
  schemas: [CatalogSearchRequest, MCPInventoryQuery]
  key: sku (item_id on negotiate)
  relationships:
  - {has_many: Contract, via: item_id}
  - {has_one: PriceBand, via: sku, note: 'operator-set (update_price_band_config)'}
  - {has_many: CatalogItem, via: related_skus, note: 'MRO rows only'}
- name: Contract
  description: The unit of purchase in the alias AP2 flow. Created PENDING by negotiate with terms (unit_price_usd, total_price_usd, Diplomat-personalised), moved to SIGNED by sign (buyer_signature), to EXECUTED by execute. Deals >= USD 100 also carry a StrategistReview.
  schemas: [AP2NegotiateBody, AP2SignBody, AP2ExecuteBody]
  key: contract_id
  relationships:
  - {belongs_to: BuyerAgent, via: buyer_did}
  - {belongs_to: CatalogItem, via: item_id}
  - {has_one: Execution, via: contract_id}
  - {has_one: StrategistReview, via: contract_id, note: 'GET /api/ap2/review/{contract_id}; approve/reject by path_id (operator)'}
  - {has_many: Dispute, via: contract_id}
- name: Execution
  description: The delivered result of an executed contract — a Grok intel answer, a report, a DID verification (status verify_delivered) or a proof. Read back at GET /api/intel/{execution_id}; listed at GET /api/ap2/executions and GET /api/intel.
  schemas: []
  key: execution_id
  relationships:
  - {belongs_to: Contract, via: contract_id}
  - {has_one: Invoice, via: execution_id, note: 'skipped when dry_run'}
  - {has_one: SettlementRecord, via: execution_id}
  - {has_many: Dispute, via: execution_id}
- name: Invoice
  description: 'Persistent invoice generated by every execution ("Every execution generates a persistent invoice. CEO endpoint: GET /api/invoices").'
  key: not exposed to buyers
  relationships:
  - {belongs_to: Execution, via: execution_id}
- name: SettlementRecord
  description: Wise USD settlement state per execution; auto-confirmed from inbound Wise webhooks (POST /api/webhooks/wise) or manually (post_settlement_confirm, operator).
  schemas: [SettlementConfirmBody]
  key: execution_id / wise_reference
  relationships:
  - {belongs_to: Execution, via: execution_id}
- name: Intent
  description: Legacy three-step flow, step 1 (submit_intent). Carries items[], subtotal, currency, delivery_region, payment_method_preference.
  schemas: [AP2IntentRequest, CheckoutRequest]
  key: intent_id
  relationships:
  - {belongs_to: BuyerAgent, via: buyer_did}
  - {has_one: Cart, via: intent_id, note: 'sign_cart/{intent_id} produces the signed cart'}
- name: Cart
  description: Legacy flow step 2/3 — a signed cart mandate executed with payment_proof (execute_payment/{cart_id}); readable at GET /api/ap2/cart/{cart_id}.
  key: cart_id
  relationships:
  - {belongs_to: Intent, via: intent_id}
- name: Subscription
  description: A buyer's plan instance (plan_sku, status, usage_count, usage_limit, queries_remaining, next_billing — fields named in the card's proof capability). Usage at GET /api/subscriptions/{subscription_id}/usage; deliveries pulled at GET /api/subscriptions/delivery.
  key: subscription_id
  relationships:
  - {belongs_to: BuyerAgent, via: buyer_did}
  - {belongs_to: SubscriptionPlan, via: plan_sku}
  - {has_many: Execution, via: subscription_id, note: 'covered units at $0.00'}
  - {has_many: Proof, via: subscription_id}
- name: SubscriptionPlan
  description: One of three plan SKUs in the agent card (intel monthly active; compliance and wolfpack future) plus the annual intel variant in the catalog.
  key: sku
  relationships:
  - {has_many: Subscription, via: plan_sku}
  - {covers: CatalogItem, via: 'covers[]'}
- name: TrialGrant
  description: Free 24-hour trial of merchant0-intel-001, one per DID, redeemed with trial_id + trial_nonce.
  schemas: [TrialGrantBody, TrialExecuteBody]
  key: trial_id
  relationships:
  - {belongs_to: BuyerAgent, via: buyer_did}
  - {belongs_to: ReferralCode, via: referral_code, note: optional}
- name: Dispute
  description: Buyer-filed dispute on a contract/execution (dispute_type, description); resolved by the Advocate (operator).
  schemas: [DisputeFileRequest, DisputeResolveRequest]
  key: dispute_id
  relationships:
  - {belongs_to: BuyerAgent, via: buyer_did}
  - {belongs_to: Contract, via: contract_id}
  - {belongs_to: Execution, via: execution_id, note: optional}
- name: Proof
  description: Signed subscription-status attestation (proof_id, subject_did, issued_by, issued_at, expires_at +24h, proof_hash sha256/32, merchant_signature). Stateless — not persisted.
  key: proof_id
  relationships:
  - {belongs_to: Subscription, via: subscription_id}
- name: ScoutProposal
  description: Operator-side opportunity proposals approved/rejected/vetoed by the CEO; not a buyer entity.
  schemas: [ScoutApproveRequest, ScoutRejectRequest, ScoutVetoRequest]
  key: proposal_id
  relationships: []
- name: OutboundTarget
  description: Operator-side outreach targets (add_outbound_target / run_outbound_now).
  schemas: [OutboundAddTargetBody]
  key: not exposed
  relationships: []
operator_only_schemas: [CreditLimitUpdateRequest, HarvestThresholdUpdateRequest, EmergencyActionRequest, PriceBandUpdateRequest, ReputationResetRequest, WhitelistMutateRequest, StrategistGenerateRequest, Ap2StrategistReviewActionBody, DiscoveryHitBody]
render: null