ghost-x402-market-intel-vet-schema

Search the web and get the results, in ONE payment. Ghost runs the search on its own provider account and returns the actual results — organic hits with title, url and snippet, plus answer box, knowledge panel, related questions — normalised into one shape. Three things most paid search tools do not do: it runs on more than one search provider and fails over between them, so a dead upstream costs you a retry rather than an answer; it never charges you for a search that did not come back, returning the fee as credit instead; and every answer carries a DSSE-signed receipt naming the provider that actually served it, over your question and the results, so what your agent retrieved can be proven later. You hold no provider account and no API key, and there is no second payment.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "What to search the web for.",
      "maxLength": 300,
      "title": "Query",
      "type": "string"
    },
    "results": {
      "default": 10,
      "description": "How many organic results to return.",
      "maximum": 100,
      "minimum": 1,
      "title": "Results",
      "type": "integer"
    },
    "country": {
      "default": "",
      "description": "Country code for localisation, e.g. 'us', 'de'.",
      "maxLength": 8,
      "title": "Country",
      "type": "string"
    },
    "language": {
      "default": "",
      "description": "Interface language, e.g. 'en', 'es'.",
      "maxLength": 8,
      "title": "Language",
      "type": "string"
    },
    "payment_signature": {
      "type": "string",
      "description": "x402 PAYMENT-SIGNATURE header value. Omit it to receive the payment terms; call again with it to run the tool."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "description": "What a buyer asks Verified Web Search for. One field is required: the query.\n\nThe provider-selection knobs this carried before (min_payers, max_price_usd,\nnetwork) described a pick the buyer then had to pay for separately. On the merchant\npath Ghost makes that choice itself and eats the upstream cost, so the buyer's only\ninputs are about the search.",
  "title": "SearchRequest"
}

Has this published JSON Schema or OpenAPI document changed since a fingerprint you hold? The schema-drift recheck of the pre-spend policy: run it when a provider's published contract may have moved before you pay it again. Paid per call via x402; DSSE-signed receipt.

{
  "type": "object",
  "properties": {
    "url": {
      "description": "Public URL of a JSON Schema or OpenAPI document",
      "maxLength": 2048,
      "title": "Url",
      "type": "string"
    },
    "known_fingerprint": {
      "default": "",
      "description": "The fingerprint from a previous check. Empty means first observation.",
      "maxLength": 128,
      "title": "Known Fingerprint",
      "type": "string"
    },
    "payment_signature": {
      "type": "string",
      "description": "x402 PAYMENT-SIGNATURE header value. Omit it to receive the payment terms; call again with it to run the tool."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false,
  "description": "What a buyer sends.",
  "title": "CheckRequest"
}

Before paying an x402 seller you do not know: settlement history, payer structure, funding links, endpoint liveness, quote-vs-advertised price. Use when one named provider or payment address is already in hand and you need a verdict before you pay it. PROCEED/CAUTION/REJECT/INSUFFICIENT_EVIDENCE with a signed receipt. Paid per call via x402.

{
  "type": "object",
  "properties": {
    "address": {
      "default": "",
      "description": "The seller's payment address (payTo). Optional if endpoint_url is given — the 402 names its own address.",
      "maxLength": 64,
      "title": "Address",
      "type": "string"
    },
    "endpoint_url": {
      "default": "",
      "description": "The seller's paid endpoint, probed with one unpaid request to read its x402 terms.",
      "maxLength": 2048,
      "title": "Endpoint Url",
      "type": "string"
    },
    "advertised_amount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The price a listing advertised, in minor units, to compare against the live quote.",
      "title": "Advertised Amount"
    },
    "payment_signature": {
      "type": "string",
      "description": "x402 PAYMENT-SIGNATURE header value. Omit it to receive the payment terms; call again with it to run the tool."
    }
  },
  "additionalProperties": false,
  "description": "What a buyer agent asks about a seller it is considering paying.",
  "title": "VetRequest"
}

Decide which x402 provider to pay, before paying it. Consult when the provider is unknown, when a decision you hold has passed its valid_until, or when the price, health, verdict or funding of one materially changed. Finds providers by need and ranks them by real economic evidence: independent payers, calls-per-payer (the repeat signature), last settlement, on-chain trust verdicts and change history. Returns USE/WATCH/AVOID with the exact call, a fallback, valid_until and recheck_when — reuse a held decision until it expires or a trigger fires, rather than asking again. Paid per call via x402; free preflight at /v1/commerce/search/preflight (3/day).

{
  "type": "object",
  "properties": {
    "query": {
      "default": "",
      "description": "Free-text need, e.g. 'solana market data with recent buyers'",
      "maxLength": 300,
      "title": "Query",
      "type": "string"
    },
    "capability": {
      "default": "",
      "description": "Capability keyword(s), e.g. 'search'",
      "maxLength": 120,
      "title": "Capability",
      "type": "string"
    },
    "network": {
      "default": "",
      "description": "CAIP-2 filter, e.g. eip155:8453",
      "maxLength": 64,
      "title": "Network",
      "type": "string"
    },
    "max_price_usd": {
      "default": 0,
      "description": "0 means no price ceiling",
      "maximum": 100,
      "minimum": 0,
      "title": "Max Price Usd",
      "type": "number"
    },
    "min_payers": {
      "default": 0,
      "description": "Only providers with at least this many independent payers in 30d",
      "maximum": 10000,
      "minimum": 0,
      "title": "Min Payers",
      "type": "integer"
    },
    "limit": {
      "default": 10,
      "maximum": 50,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    },
    "payment_signature": {
      "type": "string",
      "description": "x402 PAYMENT-SIGNATURE header value. Omit it to receive the payment terms; call again with it to run the tool."
    }
  },
  "additionalProperties": false,
  "description": "What an agent asks the market-intelligence SKU.",
  "title": "CommerceSearchRequest"
}

THE PRE-SPEND GATE. Call this immediately before your agent pays an x402/API provider, with the task's own economics. Returns ALLOW / FALLBACK / DECLINE / INSUFFICIENT_EVIDENCE — not advice: a decision your payment path should enforce. It joins the provider's measured record (independent payers, concentration, price drift, reachability, funding links, on-chain verdict) to YOUR numbers (customer_revenue, value_of_success, max_budget, required_margin, failure_cost, switching_cost) and answers the question ranking cannot: is paying for THIS task profitable, and at which provider. Where the task's value is known it maximises expected net value; where it is not, it minimises cost per verified success — which is why it will refuse the cheapest call when a cheaper provider succeeds less often. Unknown economics stay UNKNOWN and are never invented. Report the result afterwards to /v1/gate/outcome (free) — that is the only source of the success rates it uses. Paid per decision via x402, or drawn from prepaid credit; a cached decision inside valid_until and an INSUFFICIENT_EVIDENCE answer are free.

{
  "type": "object",
  "properties": {
    "task_id": {
      "maxLength": 200,
      "title": "Task Id",
      "type": "string"
    },
    "task_type": {
      "description": "What kind of job this is. Success history is pooled under it, so it must be stable.",
      "maxLength": 120,
      "title": "Task Type",
      "type": "string"
    },
    "success_definition": {
      "description": "What counts as success, written down BEFORE paying. verified_success is later judged against this.",
      "maxLength": 1000,
      "title": "Success Definition",
      "type": "string"
    },
    "provider_candidates": {
      "items": {
        "$ref": "#/$defs/ProviderCandidateModel"
      },
      "maxItems": 20,
      "minItems": 1,
      "title": "Provider Candidates",
      "type": "array"
    },
    "currency": {
      "default": "USD",
      "maxLength": 16,
      "title": "Currency",
      "type": "string"
    },
    "customer_revenue": {
      "anyOf": [
        {
          "maximum": 100000000,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Customer Revenue"
    },
    "value_of_success": {
      "anyOf": [
        {
          "maximum": 100000000,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Value Of Success"
    },
    "max_budget": {
      "anyOf": [
        {
          "maximum": 100000000,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Budget"
    },
    "required_margin": {
      "anyOf": [
        {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Required Margin"
    },
    "failure_cost": {
      "anyOf": [
        {
          "maximum": 100000000,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Failure Cost"
    },
    "switching_cost": {
      "anyOf": [
        {
          "maximum": 100000000,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Switching Cost"
    },
    "revenue_models": {
      "description": "Optional. Say what the task is worth in the terms you actually measure, and Ghost derives value_of_success / customer_revenue / max_budget from it — never overriding a value you stated yourself. Each entry needs a `type`: SALES_ROI (spend, qualified_leads?, meetings?, closed_deals?, realized_revenue?), AFFILIATE_ROI (commission_rate?, order_value?, conversion_probability?, tool_cost?, inference_cost?, transaction_cost?), PROCUREMENT_SAVINGS (current_total_cost?, alternative_total_cost?, switching_cost?, migration_cost?), RETURN_ROI (expected_return, data_cost?, model_cost?, execution_cost?, expected_risk_loss?; expected_return is YOURS to state and is never estimated by Ghost), CREDIT_AFFORDABILITY (available_credit, planned_spend?). Ratios are derived only where the denominator exists; conversion rates are never invented.",
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "maxItems": 6,
      "title": "Revenue Models",
      "type": "array"
    },
    "fallback_authorized": {
      "default": false,
      "description": "May Ghost route to a different candidate than the first? Off by default: an unrequested reroute is a payment the operator did not choose.",
      "title": "Fallback Authorized",
      "type": "boolean"
    },
    "payment_signature": {
      "type": "string",
      "description": "x402 PAYMENT-SIGNATURE header value. Omit it to receive the payment terms; call again with it to run the tool."
    }
  },
  "required": [
    "task_id",
    "task_type",
    "success_definition",
    "provider_candidates"
  ],
  "$defs": {
    "ProviderCandidateModel": {
      "additionalProperties": false,
      "description": "One provider the task could pay, as the caller's own payment path sees it.",
      "properties": {
        "provider": {
          "description": "Resource URL or payee address of the candidate",
          "maxLength": 2048,
          "title": "Provider",
          "type": "string"
        },
        "quoted_cost": {
          "anyOf": [
            {
              "maximum": 1000000,
              "minimum": 0,
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "What this provider quoted for this call, in `currency`. Prefer the LIVE 402 amount over an advertised price — the two disagreeing is itself a recheck trigger.",
          "title": "Quoted Cost"
        },
        "payee": {
          "default": "",
          "maxLength": 64,
          "title": "Payee",
          "type": "string"
        },
        "network": {
          "default": "",
          "description": "CAIP-2, e.g. eip155:8453",
          "maxLength": 64,
          "title": "Network",
          "type": "string"
        }
      },
      "required": [
        "provider"
      ],
      "title": "ProviderCandidateModel",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "The inline pre-spend gate's input: one task, its economics, its candidates.\n\nEvery optional economic field is genuinely optional and stays UNKNOWN. Ghost will not\nsubstitute a default revenue or an assumed margin — a gate that invents the numbers\nit gates on is not a control.",
  "title": "GateDecideRequest"
}