SpendGate

Score one planned payment before it is sent: a crypto transfer, gift card, subscription, or paid API or merchant. Do not use it for a pure read, or for a status_check under $1 you will not pay; that still burns a free score and approves unless a budget you pass is exceeded. Each call uses one free score (anonymous 100/UTC day, sg_live_ key 1,000 from get_api_key). Past that cap the call is HTTP 402 and costs 0.001 USDC on Base via x402. It does not pay the merchant. A domain, https URL, or 0x payee that is not on the local known-host list is checked with PayCheck. Trusted counts as a known merchant. Block means do not pay, including under the micro threshold. If PayCheck is unreachable, local merchant rules are used and the score still returns. While free quota remains, the same arguments consume another score. category overrides purpose. When category is omitted, purpose is matched as a category name; any other prose is unknown risk. merchant overrides endpoint when both are set. A set daily_budget_remaining or monthly_budget_remaining blocks when amount is greater; omitted budgets are skipped. Returns score 0-100, verdict approve|ask_human|block, reasons, recommended_action, checked_at, detail, and quota (daily_limit, used_today, remaining_today, paid_today, resets_at). approve means pay; ask_human means stop for a person; block means do not pay. Read the cap with get_quota instead of spending a score.

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "description": "Planned spend in USD, not token atomic units. Required."
    },
    "currency": {
      "type": "string",
      "description": "Payment currency. Defaults to USDC."
    },
    "category": {
      "type": "string",
      "description": "Risk class. Wins over purpose. One of status_check, api_call, saas, infra, gift_card, crypto_transfer, irreversible. Any other string is unknown risk."
    },
    "purpose": {
      "type": "string",
      "description": "Short note, max 280 characters. When category is omitted, this text is matched as a category name; other prose is unknown risk. When category is set, this is echoed and not scored."
    },
    "merchant": {
      "type": "string",
      "description": "Payee name or https URL. Used instead of endpoint when both are set. A missing payee is penalized."
    },
    "endpoint": {
      "type": "string",
      "description": "Payee used only when merchant is omitted. Ignored if merchant is also set."
    },
    "agent_id": {
      "type": "string",
      "description": "Agent or key id. Echoed, not scored in v1."
    },
    "api_key": {
      "type": "string",
      "description": "Optional sg_live_ key. Uses the 1,000/day bucket. An unrecognized key returns invalid_api_key instead of falling back to anonymous."
    },
    "daily_budget_remaining": {
      "type": "number",
      "description": "USD left today. When set, a greater amount is blocked. Omit to skip this check."
    },
    "monthly_budget_remaining": {
      "type": "number",
      "description": "USD left this month. When set, a greater amount is blocked. Omit to skip this check."
    },
    "risk_hints": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Self-reported hints. Raising: new_payee, new_merchant, first_payment, high_velocity, mismatched_purpose, off_platform, shared_wallet. Lowering: trusted_repeat, within_policy, human_preapproved. known_merchant marks the payee known."
    }
  },
  "required": [
    "amount"
  ],
  "additionalProperties": false
}

Read today's free-score balance. Prefer this over score_spend when you are not judging a specific payment, including before a batch or after a 402: it does not consume a score, returns no verdict, and is never billed. Do not use it to approve or block a spend. Pass api_key for that sg_live_ key (tier free, 1,000/UTC day); omit it for this client's anonymous bucket (tier anonymous, 100/UTC day). An unrecognized or non-sg_live_ key returns invalid_api_key and does not fall back. Returns subject (anonymous|api_key|bundle), key_id, key_prefix, tier (anonymous|free|bundle), daily_limit, used_today, remaining_today, paid_today, price_usd, price_atomic, asset (USDC), network, resets_at (next UTC midnight), and paid_configured. Mint a higher cap with get_api_key.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Optional sg_live_ key to read. Omit for the anonymous bucket. Does not mint a key. An unrecognized key returns invalid_api_key."
    }
  },
  "additionalProperties": false
}

Mint one free sg_live_ key so later score_spend and get_quota calls use 1,000 scores per UTC day instead of the anonymous 100. Call once per agent when you will score often and have no stored key. Do not call every turn, do not mint again if you already stored the secret, and do not call just to read remaining scores (use get_quota). Returns the secret once as api_key, plus key_id, key_prefix, label, tier free, daily_limit, created_at, and note. Only a hash is stored, so the secret cannot be shown again. Keys do not expire and there is no revoke tool; a lost key stays valid, and an unknown or non-sg_live_ value later returns invalid_api_key. At most 20 mints per client per UTC day, then key_mint_limit and no new key. Minting is free and does not consume a score. Send the secret later as Authorization: Bearer or as api_key. label is an optional stored name and does not set a cap, a scope, or an expiry.

{
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Optional name stored with the key, up to 80 characters. Does not set a cap or an expiry. Keys do not expire."
    }
  },
  "additionalProperties": false
}