Onyx MCP

{
  "type": "object",
  "properties": {
    "max_pages": {
      "type": "integer",
      "description": "Bazaar pages (100 resources each) to scan for the live census. Default 300 = full sweep (~28k). Lower it for a faster, sampled concentration read."
    }
  }
}

{
  "type": "object",
  "required": [],
  "properties": {
    "action": {
      "enum": [
        "census",
        "probe"
      ],
      "type": "string",
      "default": "census",
      "description": "'census' = fast structural audit (no live calls). 'probe' = census + live hollow-detection on a sample."
    },
    "sample": {
      "type": "integer",
      "default": 5,
      "description": "For action='probe': how many agents to live-test (bounded 1-12, default 5). Probed in listed order."
    },
    "registry_url": {
      "type": "string",
      "default": "https://www.a2aregistry.org/api/agents?limit=500",
      "description": "Registry agents API. Default a2aregistry.org."
    }
  }
}

{
  "type": "object",
  "required": [
    "target"
  ],
  "properties": {
    "target": {
      "type": "string",
      "description": "The agent to verify: its A2A endpoint URL, or its /.well-known/agent-card.json URL, or its base origin."
    }
  }
}

{
  "type": "object",
  "required": [
    "brand"
  ],
  "properties": {
    "brand": {
      "type": "string",
      "description": "Brand, product, company, or entity to measure (e.g. 'Onyx Protocol', 'Stripe')."
    },
    "category": {
      "type": "string",
      "description": "Optional product category for the recommendation-set probe (e.g. 'AI agent payment rails', 'running shoes'). Drives the 'best <category>' query."
    },
    "competitors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional competitor names to compute share-of-voice against."
    }
  }
}

{
  "type": "object",
  "required": [
    "payload"
  ],
  "properties": {
    "payload": {
      "type": "object",
      "description": "The full Onyx-signed result to verify, including its onyx_attestation block (exactly as returned by an Onyx tool)."
    }
  }
}

{
  "type": "object",
  "required": [
    "address"
  ],
  "properties": {
    "deep": {
      "type": "boolean",
      "default": true,
      "description": "Run the optional AI deep-pass for novel/business-logic bugs (only fires if the server has an AI key configured; degrades gracefully otherwise)."
    },
    "address": {
      "type": "string",
      "description": "Contract address on Base mainnet (0x... 20-byte hex)."
    }
  }
}

{
  "type": "object",
  "properties": {
    "census_limit": {
      "type": "integer",
      "default": 500,
      "maximum": 1000,
      "minimum": 50,
      "description": "How many CDP discovery entries to sample for the census (top categories)."
    }
  }
}

{
  "type": "object",
  "required": [
    "action"
  ],
  "properties": {
    "kind": {
      "type": "string",
      "description": "contribute: observation kind (merchant_reality|agent_sighting|price_observation|standards_datapoint|counterparty_fact)."
    },
    "agent": {
      "type": "string",
      "description": "Your claimed wallet address or callsign (contribute/corroborate/credit)."
    },
    "limit": {
      "type": "integer",
      "description": "work/pool: max rows (default 25)."
    },
    "action": {
      "enum": [
        "contribute",
        "corroborate",
        "work",
        "pool",
        "credit"
      ],
      "type": "string",
      "description": "What to do on the exchange."
    },
    "stance": {
      "enum": [
        "agree",
        "dispute"
      ],
      "type": "string",
      "description": "corroborate: agree (default) or dispute."
    },
    "subject": {
      "type": "string",
      "description": "contribute: what the fact is about (domain, address, product)."
    },
    "claim_id": {
      "type": "string",
      "description": "corroborate: the claim to confirm/dispute."
    },
    "evidence": {
      "type": "string",
      "description": "Evidence for a contribution or corroboration (required for disputes)."
    },
    "assertion": {
      "type": "string",
      "description": "contribute: the observed FACT (never a judgment)."
    }
  }
}

{
  "type": "object",
  "required": [
    "agent_id"
  ],
  "properties": {
    "peek": {
      "type": "boolean",
      "default": false,
      "description": "If true, don't mark messages read."
    },
    "limit": {
      "type": "integer",
      "default": 100,
      "description": "Max messages to return (<=500)."
    },
    "agent_id": {
      "type": "string",
      "description": "You: agent name/callsign, or 0x address / did:pkh."
    },
    "unread_only": {
      "type": "boolean",
      "default": false,
      "description": "Only return unread messages."
    }
  }
}

{
  "type": "object",
  "required": [
    "to"
  ],
  "properties": {
    "to": {
      "type": "string",
      "description": "Recipient: agent name/callsign, or 0x address / did:pkh."
    },
    "from": {
      "type": "string",
      "description": "Who it's from (your agent name/id). Optional."
    },
    "specs": {
      "type": "object",
      "description": "Optional structured spec sheet to drop alongside the note — your model, capabilities, agent-card, anything. Preserved verbatim so the recipient sees who you are, not just text."
    },
    "message": {
      "type": "string",
      "description": "The message to leave."
    }
  }
}

{
  "type": "object",
  "required": [
    "target"
  ],
  "properties": {
    "target": {
      "type": "string",
      "description": "URL of the service/agent to rate (e.g. https://example.com or its x402 base)."
    }
  }
}

{
  "type": "object",
  "required": [
    "domain"
  ],
  "properties": {
    "brand": {
      "type": "string",
      "description": "Optional brand name you believe this storefront represents (e.g. 'Russell & Bromley'). Enables the brand-similarity observation."
    },
    "domain": {
      "type": "string",
      "description": "Storefront domain or URL, e.g. brand-outlet-sale.com or https://shop.example.com/p/1"
    },
    "product_url": {
      "type": "string",
      "description": "Optional specific product URL to extract the observed price from (defaults to the domain root)."
    },
    "expected_price": {
      "type": "number",
      "description": "Optional price you were quoted/expect. If the page shows a price, the deviation percentage is reported as a fact."
    }
  }
}

{
  "type": "object",
  "required": [
    "brand"
  ],
  "properties": {
    "runs": {
      "type": "integer",
      "description": "Runs per prompt (default 3, max 5). More runs = tighter confidence interval on the score."
    },
    "brand": {
      "type": "string",
      "description": "Brand, product, protocol, or agent to score (e.g. '0n1x', 'Stripe')."
    },
    "domain": {
      "type": "string",
      "description": "Optional canonical domain (e.g. '0n1x.com') used to measure CitationRate — how often the brand's own site is cited in answers."
    },
    "aliases": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional alternate names that count as the brand (e.g. ['Onyx'] for a rename). Any alias match = brand present."
    },
    "category": {
      "type": "string",
      "description": "Category for the buyer-intent prompts (e.g. 'agent trust layer', 'payment processors'). Drives the 'best <category>' / 'verify before pay' style queries."
    },
    "competitors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional competitor names for position-weighted share-of-voice."
    }
  }
}

{
  "type": "object",
  "required": [],
  "properties": {
    "chain": {
      "enum": [
        "base"
      ],
      "type": "string",
      "description": "Chain to read (default 'base' = Base mainnet, eip155:8453)."
    },
    "address": {
      "type": "string",
      "description": "Optional agent EVM address (0x...) to check for an ERC-8004 identity (balanceOf > 0)."
    },
    "registry": {
      "enum": [
        "identity",
        "reputation"
      ],
      "type": "string",
      "description": "Which singleton to read (default 'identity')."
    }
  }
}

{
  "type": "object",
  "required": [
    "action",
    "grant"
  ],
  "properties": {
    "grant": {
      "type": "object",
      "description": "The agent's permission grant (onyx-perm-grant/v0): allowed_actions, allowed_merchants, allowed_domains, spend_max_usdc, spend_window_usdc, spend_window_sec, velocity_max, per_counterparty_budget, principal, consent_ref, expires_at"
    },
    "action": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "e.g. transact, verify, read"
        },
        "domain": {
          "type": "string"
        },
        "merchant": {
          "type": "string"
        },
        "amount_usdc": {
          "type": "number"
        }
      },
      "description": "The proposed action: {type, amount_usdc?, merchant?, domain?}"
    },
    "history": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Optional: recent settled actions for window/velocity checks, each {amount_usdc, ts (unix), counterparty?}. Stateless — the caller supplies the tally; the fact binds to it."
    }
  }
}

{
  "type": "object",
  "required": [
    "agent"
  ],
  "properties": {
    "agent": {
      "type": "string",
      "description": "Who is granted (did:pkh / wallet / agent id)"
    },
    "purpose": {
      "type": "string"
    },
    "principal": {
      "type": "string",
      "description": "Who grants the authority (did / email / org)"
    },
    "expires_at": {
      "type": "integer",
      "description": "Unix time the grant lapses"
    },
    "consent_ref": {
      "type": "string",
      "description": "Proof of consent (AP2 mandate id / signature hash)"
    },
    "velocity_max": {
      "type": "integer",
      "description": "Max number of transacts per window"
    },
    "spend_max_usdc": {
      "type": "number",
      "description": "Hard ceiling per action"
    },
    "allowed_actions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Subset of ['read', 'verify', 'transact', 'sign', 'negotiate', 'subscribe']; deny-by-default"
    },
    "allowed_domains": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "spend_window_sec": {
      "type": "integer",
      "description": "Window length in seconds (default 86400)"
    },
    "allowed_merchants": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "spend_window_usdc": {
      "type": "number",
      "description": "Optional rolling-window aggregate cap"
    },
    "per_counterparty_budget": {
      "type": "number",
      "description": "Max aggregate spend per single counterparty per window"
    }
  }
}

{
  "type": "object",
  "properties": {
    "agent": {
      "type": "object",
      "description": "Optional: the agent's record (name, description, skills, and any permission fields) for a deeper scan"
    },
    "endpoint": {
      "type": "string",
      "description": "The agent's endpoint URL"
    }
  }
}

{
  "type": "object",
  "required": [
    "domain"
  ],
  "properties": {
    "brand": {
      "type": "string",
      "description": "Optional brand the merchant CLAIMS to be (e.g. 'Russell & Bromley'). If a well-known brand is claimed on a freshly-registered domain, the clearance is HELD — the cloned-storefront pattern."
    },
    "domain": {
      "type": "string",
      "description": "Merchant domain or URL you are about to pay, e.g. shop.example.com"
    },
    "amount_usd": {
      "type": "number",
      "description": "Optional amount you are about to pay (for the record; large amounts lower the auto-PROCEED bar)."
    },
    "product_url": {
      "type": "string",
      "description": "Optional specific product URL to read the observed price from."
    },
    "expected_price": {
      "type": "number",
      "description": "Optional price you were quoted/expect. If the page shows a price, a large deviation downgrades the clearance."
    }
  }
}

{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "description": "The x402-gated endpoint to preflight (http:// or https://)."
    },
    "timeout_seconds": {
      "type": "number",
      "default": 8,
      "description": "Probe timeout in seconds. Clamped to [2, 15]."
    }
  }
}

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "Research question or keyword string. Plain English works; OpenAlex handles tokenization."
    },
    "top_n": {
      "type": "integer",
      "default": 5,
      "maximum": 20,
      "minimum": 1,
      "description": "How many papers to return."
    },
    "sort_by": {
      "enum": [
        "relevance",
        "citations",
        "recency"
      ],
      "type": "string",
      "default": "relevance",
      "description": "Ranking. citations = highest cited first; recency = newest first; relevance = OpenAlex semantic match."
    },
    "year_from": {
      "type": "integer",
      "maximum": 2100,
      "minimum": 1900,
      "description": "Optional: only return papers from this year onward."
    },
    "min_citations": {
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "description": "Filter out papers with fewer than this many citations. Use 50+ to surface only well-known work."
    }
  }
}

{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "description": "Full product page URL (http/https). The exact page whose price + availability you want observed."
    },
    "expect_price": {
      "type": "number",
      "description": "Optional. A price you believe is current. If given, the result includes matches_expected:bool + drift so a caller can detect a stale/hallucinated quote."
    }
  }
}

{
  "type": "object",
  "required": [
    "address"
  ],
  "properties": {
    "address": {
      "type": "string",
      "description": "The agent's self-custody Base/EVM address, 0x-prefixed (42 chars)."
    }
  }
}

{
  "type": "object",
  "required": [
    "agent"
  ],
  "properties": {
    "agent": {
      "type": "string",
      "description": "Agent the mandate authorizes (address or callsign)."
    },
    "purpose": {
      "type": "string",
      "description": "Human-readable purpose of the mandate."
    },
    "principal": {
      "type": "string",
      "description": "Optional: the human/entity granting authority."
    },
    "expires_at": {
      "type": "integer",
      "description": "Unix time the mandate lapses."
    },
    "velocity_max": {
      "type": "integer",
      "description": "Max number of transactions per window."
    },
    "daily_cap_usdc": {
      "type": "number",
      "description": "Rolling 24h aggregate cap (USDC)."
    },
    "spend_max_usdc": {
      "type": "number",
      "description": "Hard ceiling per single action (USDC)."
    },
    "allowed_actions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Permitted action verbs (deny by default)."
    },
    "allowed_domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Domain allowlist (deny by default)."
    },
    "allowed_merchants": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Merchant allowlist (deny by default)."
    }
  }
}

{
  "type": "object",
  "required": [
    "domain"
  ],
  "properties": {
    "brand": {
      "type": "string",
      "description": "Optional brand the storefront claims to be (enables the impersonation-similarity observation)."
    },
    "domain": {
      "type": "string",
      "description": "Counterparty/storefront domain or URL the agent is about to pay."
    },
    "expected_price": {
      "type": [
        "number",
        "string"
      ],
      "description": "Optional price the agent expects to pay (enables the price-deviation observation)."
    }
  }
}

{
  "type": "object",
  "required": [
    "recipient",
    "amount_usdc"
  ],
  "properties": {
    "recipient": {
      "type": "string",
      "description": "0x recipient address the agent is about to pay (Base)."
    },
    "amount_usdc": {
      "type": "number",
      "description": "Amount about to be sent, in USDC. Drives both the risk threshold and the take-rate quote."
    },
    "contract_address": {
      "type": "string",
      "description": "Optional. If the payment interacts with a contract, its 0x address — triggers a full contract audit."
    },
    "counterparty_agent_id": {
      "type": "integer",
      "description": "Optional. If paying another AI agent, its ERC-8004 id — triggers a reputation check."
    }
  }
}

{
  "type": "object",
  "required": [
    "typed_data"
  ],
  "properties": {
    "typed_data": {
      "type": "object",
      "description": "The full EIP-712 typed-data object the agent is about to sign: {domain, primaryType, types, message}."
    }
  }
}

{
  "type": "object",
  "required": [
    "contract"
  ],
  "properties": {
    "chain": {
      "type": "string",
      "default": "base",
      "description": "Chain the token lives on. Name ('base','ethereum','bsc','polygon','arbitrum','optimism','avalanche') or numeric chain id. Default 'base'."
    },
    "contract": {
      "type": "string",
      "description": "Token contract address (0x… 20-byte hex) to screen."
    }
  }
}

{
  "type": "object",
  "required": [],
  "properties": {
    "tool": {
      "type": "string",
      "description": "Optional. Restrict the track record to one tool (e.g. onyx_tx_guard)."
    }
  }
}

{
  "type": "object",
  "required": [
    "address"
  ],
  "properties": {
    "address": {
      "type": "string",
      "description": "0x recipient address your agent is about to send funds to (Base mainnet)."
    },
    "amount_usdc": {
      "type": "number",
      "description": "Optional amount about to be sent (USDC). Larger amounts raise the review threshold."
    }
  }
}

{
  "type": "object",
  "required": [
    "to"
  ],
  "properties": {
    "to": {
      "type": "string",
      "description": "The transaction's `to` address (target contract or recipient). Required."
    },
    "data": {
      "type": "string",
      "description": "The transaction calldata (0x-hex). Omit/empty for a plain ETH transfer."
    },
    "value_wei": {
      "type": "string",
      "description": "Optional. ETH value being sent, in wei (base-10 string)."
    }
  }
}

{
  "type": "object",
  "required": [
    "domain"
  ],
  "properties": {
    "domain": {
      "type": "string",
      "description": "The domain to verify, e.g. shop.example.com (your storefront/agent endpoint)."
    },
    "contact": {
      "type": "string",
      "description": "Optional contact (email/handle) recorded with the issuance for renewal notices."
    },
    "agent_id": {
      "type": "string",
      "description": "Optional agent id to cross-link this verified domain to an agent identity."
    }
  }
}

{
  "type": "object",
  "required": [
    "payment_requirements"
  ],
  "properties": {
    "now_unix": {
      "type": "integer",
      "description": "Override current unix time for replay/CI use. Defaults to now."
    },
    "x_payment_b64": {
      "type": "string",
      "description": "Base64-encoded X-PAYMENT (v2 PAYMENT-SIGNATURE) header value. Optional if payment_payload provided."
    },
    "payment_payload": {
      "type": "object",
      "description": "Decoded payment payload dict. Use this OR x_payment_b64."
    },
    "payment_requirements": {
      "type": "object",
      "description": "Expected paymentRequirements from the 402 challenge ({scheme, network, payTo, asset, maxAmountRequired, maxTimeoutSeconds, ...})."
    }
  }
}

{
  "type": "object",
  "required": [
    "tx_hash"
  ],
  "properties": {
    "network": {
      "enum": [
        "base",
        "base-sepolia"
      ],
      "type": "string",
      "default": "base",
      "description": "Chain to query. Must match where the tx was mined."
    },
    "tx_hash": {
      "type": "string",
      "description": "0x-prefixed 32-byte tx hash to verify."
    },
    "expected_to": {
      "type": "string",
      "description": "Optional. Expected recipient address (0x...). If provided, verifier checks Transfer.to matches."
    },
    "expected_from": {
      "type": "string",
      "description": "Optional. Expected sender address (0x...). If provided, verifier checks Transfer.from matches."
    },
    "expected_amount_usdc": {
      "type": "number",
      "description": "Optional. Expected USDC amount (whole USDC, not atomic). If provided, verifier checks Transfer.value matches (within 0.000001 tolerance)."
    }
  }
}