{
  "schema_version": "2026-07-30.machine-buyer-quickstart.v5",
  "title": "MachineSignal canonical machine buyer guide",
  "canonical_human_guide": "https://machinesignal.it/machine-buyer-quickstart/",
  "canonical_machine_guide": "https://machinesignal.it/machine-buyer-quickstart.json",
  "scope": "B2B Italy only",
  "entry_product": {
    "product_code": "MS-DEC-250",
    "price_eur": 49,
    "requested_outputs": 250,
    "requires_existing_company_list": true
  },
  "discovery": {
    "mcp_endpoint": "https://mcp.machinesignal.it/mcp",
    "mcp_server_card": "https://mcp.machinesignal.it/.well-known/mcp/server-card.json",
    "a2a_agent_card": "https://a2a.machinesignal.it/.well-known/agent-card.json",
    "a2a_rest_origin": "https://a2a.machinesignal.it",
    "official_registry_name": "it.machinesignal/discovery",
    "official_registry_listing": "https://registry.modelcontextprotocol.io/?search=it.machinesignal%2Fdiscovery",
    "semantic_registry_alias_name": "it.machinesignal/b2b-lead-scoring-ranking-italy",
    "semantic_registry_alias_listing": "https://registry.modelcontextprotocol.io/?search=it.machinesignal%2Fb2b-lead-scoring-ranking-italy",
    "github_documentation_repository": "https://github.com/machinesignal-it/machinesignal-machine-buyer-docs",
    "llms": "https://machinesignal.it/llms.txt",
    "identity_and_methodology": "https://machinesignal.it/chi-siamo-metodologia/",
    "product_catalog": "https://machinesignal.it/product-catalog.json",
    "lead_opportunity_score_api_landing": "https://machinesignal.it/api/lead-opportunity-score/",
    "target_company_prioritization_guide_it": "https://machinesignal.it/risorse/prioritizzazione-aziende-target-api/",
    "market_potential_analysis_api_guide_it": "https://machinesignal.it/risorse/analisi-mercato-potenziale-api/"
  },
  "read_only_flow": [
    {
      "step": 1,
      "action": "discover",
      "instruction": "Read the A2A Agent Card or MCP Server Card, then use one verified read-only discovery interface.",
      "creates_order": false
    },
    {
      "step": 2,
      "action": "check_fit",
      "mcp_tool": "check_buyer_fit",
      "arguments": {
        "country": "IT",
        "customer_type": "B2B",
        "has_existing_company_list": true,
        "requested_product_code": "MS-DEC-250"
      },
      "creates_order": false
    },
    {
      "step": 3,
      "action": "inspect_example",
      "mcp_tool": "get_synthetic_example",
      "arguments": {
        "product_code": "MS-DEC-250"
      },
      "resource_uri": "machinesignal://examples/ms-dec-250",
      "creates_order": false
    },
    {
      "step": 4,
      "action": "prepare_locally",
      "mcp_tool": "prepare_order_intent",
      "arguments": {
        "product_code": "MS-DEC-250"
      },
      "resource_uri": "machinesignal://orders/ms-dec-250/preparation",
      "accepts_buyer_data": false,
      "creates_order": false
    },
    {
      "step": 5,
      "action": "validate_locally",
      "validation_profile": "https://machinesignal.it/order-intent-validation-profile.json",
      "authoritative_openapi": "https://api.machinesignal.it/openapi.json",
      "instruction": "Fill and validate real buyer identity, tax, contact, billing and authority fields only in the buyer environment. Never send them to the discovery MCP.",
      "creates_order": false
    },
    {
      "step": 6,
      "action": "submit_once_when_authorized",
      "method": "POST",
      "endpoint": "https://api.machinesignal.it/v1/order-intents",
      "idempotency_header": "Idempotency-Key",
      "instruction": "Submit only after the buyer machine has explicit legal and business-card authority. Placeholder or test submissions are forbidden.",
      "is_real_commercial_action": true
    }
  ],
  "read_only_examples": {
    "curl_a2a_agent_card": "curl --fail --silent --show-error https://a2a.machinesignal.it/.well-known/agent-card.json",
    "curl_server_card": "curl --fail --silent --show-error https://mcp.machinesignal.it/.well-known/mcp/server-card.json",
    "curl_quickstart": "curl --fail --silent --show-error https://machinesignal.it/machine-buyer-quickstart.json",
    "python_quickstart": "import json, urllib.request\nwith urllib.request.urlopen('https://machinesignal.it/machine-buyer-quickstart.json') as r:\n    guide = json.load(r)\nprint(guide['entry_product']['product_code'])",
    "javascript_quickstart": "const guide = await fetch('https://machinesignal.it/machine-buyer-quickstart.json').then(r => r.json());\nconsole.log(guide.entry_product.product_code);"
  },
  "zero_touch_post_intent_flow": [
    {
      "step": 7,
      "action": "store_private_order_receipt",
      "instruction": "Store the one-time opaque order receipt privately and send it only as X-MachineSignal-Order-Receipt to the returned status URL."
    },
    {
      "step": 8,
      "action": "poll_authenticated_status",
      "instruction": "Poll the authenticated status. An eligible B2B Italy buyer receives a buyer-specific, one-use Stripe Checkout Session; no public Payment Link is used."
    },
    {
      "step": 9,
      "action": "pay_when_explicitly_authorized",
      "instruction": "Use the private checkout only with explicit authority to charge the buyer business card, then wait for payment_status=paid_verified."
    },
    {
      "step": 10,
      "action": "submit_paid_inputs_and_retrieve_delivery",
      "instruction": "After verified payment, submit the company-only DEC inputs through the authenticated endpoint, poll processing and retrieve the artifact with its expiring token."
    }
  ],
  "hard_boundaries": {
    "commercial_scope": "B2B Italy only",
    "foreign_demand": "research only",
    "b2c_allowed": false,
    "discovery_mcp_accepts_buyer_data": false,
    "discovery_mcp_creates_order": false,
    "discovery_mcp_returns_checkout": false,
    "internal_or_test_real_order_allowed": false,
    "outreach_or_target_contact_executed": false
  },
  "precedence": "The current production OpenAPI and runtime validation prevail if this guide differs."
}