# AllowanceGuard

Deterministic pre-approval allowance checks for Base agents, paid per call.

AllowanceGuard answers one question before an agent signs an irreversible approve: should this spender get this allowance. It reads the allowance the spender already holds, classifies the one being requested against the token's own supply rather than a list of sentinel values, and says whether signing raises or lowers exposure — so reducing an unlimited allowance is recognised as safer than the status quo instead of flagged as another approval. It checks whether the spender is a contract at all, whether its code can be swapped after the grant, and whether it is on the denylist. There is no model anywhere in it. When a fact cannot be read the answer is unknown, never a quiet allow.

## Payment

- Protocol: x402 V2, scheme `exact`, network `eip155:8453` (Base mainnet)
- Asset: USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- No accounts, no API keys, no subscriptions.
- Failed calls are not charged. Only a successful, usable result settles.
- Payment authorization window: 60s

## Endpoints

### `POST /v1/guard/allowance` — $0.015 per successful call

Decide whether to grant an ERC-20, NFT or Permit2 allowance before signing it. Send owner, token, spender and amount, or the unsigned approve, setApprovalForAll or Permit2 calldata. Returns allow, warn, block or unknown with the allowance already on chain, the requested scope and the rule behind it, whether this raises or lowers exposure, and whether the spender is a contract, upgradeable or denylisted. Returns unknown rather than guessing. Not a guarantee a spender is honest.

Unpaid request returns HTTP 402 with the challenge in the `PAYMENT-REQUIRED` header:

```bash
curl -i -sS -X POST https://allowance.schemasure.com/v1/guard/allowance \
  -H 'content-type: application/json' \
  -d '{"calldata":{"from":"0x9F2C5E4A8db1C3a7E6B0d4f8C1E2a5b7D9C0e3F4","to":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","data":"0x095ea7b30000000000000000000000002626664c2603336e57b271c5c0b26f421741e4810000000000000000000000000000000000000000000000000000000000000000"}}'
```

Example successful response:

```json
{
  "ok": true,
  "verdict": "allow",
  "confidence": 1,
  "risk_codes": [],
  "evidence": [
    {
      "code": "CURRENT_ALLOWANCE_UNREADABLE",
      "severity": "info",
      "detail": "The allowance 0x2626664c2603336E57B271c5C0b26F421741e481 already holds could not be read: no RPC endpoint is configured, so the allowance this spender already holds could not be read. Whether this request adds to an existing allowance or replaces one is therefore unknown. It does not change the answer: this request cannot increase what the spender can move.",
      "source": "rpc"
    },
    {
      "code": "SPENDER_CODE_UNREADABLE",
      "severity": "info",
      "detail": "Whether 0x2626664c2603336E57B271c5C0b26F421741e481 is a contract or an account could not be determined: no RPC endpoint is configured, so it is unknown whether the spender has code. It does not change the answer: this request cannot increase what the spender can move.",
      "source": "rpc"
    },
    {
      "code": "SPENDER_PROXY_OPAQUE",
      "severity": "info",
      "detail": "The code that would execute on 0x2626664c2603336E57B271c5C0b26F421741e481's behalf could not be resolved: no RPC endpoint is configured, so no slot could be read. An allowance to a contract whose executing code is unknown is an allowance to unknown code. It does not change the answer: this request cannot increase what the spender can move.",
      "source": "rpc"
    }
  ],
  "result": {
    "input_shape": "calldata",
    "chain": "eip155:8453",
    "request": {
      "kind": "erc20_approve",
      "mode": "absolute",
      "owner": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4",
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "spender": "0x2626664c2603336E57B271c5C0b26F421741e481",
      "amount": "0",
      "expiration": null,
      "deadline": null,
      "token_id": null,
      "target": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "summary": "Revoke 0x2626664c2603336E57B271c5C0b26F421741e481's allowance on token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 by setting it to zero."
    },
    "decode": {
      "selector": "0x095ea7b3",
      "signature": "approve(address,uint256)",
      "source": "bundled-abi",
      "trace": [
        "verified-abi: no candidate",
        "bundled-abi: resolved to approve(address,uint256)"
      ],
      "candidates": []
    },
    "classification": {
      "scope": "bounded",
      "subject": "resulting_allowance",
      "basis": "the allowance is zero, which is bounded without reference to the token's supply",
      "supply_checked": true,
      "total_supply": null,
      "resulting_allowance": "0"
    },
    "current": {
      "amount": null,
      "source": "unreadable",
      "expiration": null,
      "detail": "no RPC endpoint is configured, so the allowance this spender already holds could not be read"
    },
    "delta": {
      "direction": "unknown",
      "increases_exposure": false,
      "difference": null,
      "detail": "this sets the allowance to zero, which cannot increase exposure whatever it is now; the value being replaced could not be read, so whether it is a reduction or already zero is unknown"
    },
    "approval": {
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "owner": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4",
      "spender": "0x2626664c2603336E57B271c5C0b26F421741e481",
      "amount": "0",
      "scope": "bounded",
      "basis": "the allowance is zero, which is bounded without reference to the token's supply",
      "spender_is_contract": null,
      "total_supply": null,
      "expiration": null
    },
    "spender": {
      "address": "0x2626664c2603336E57B271c5C0b26F421741e481",
      "is_contract": null,
      "detail": "no RPC endpoint is configured, so it is unknown whether the spender has code",
      "proxy": {
        "address": "0x2626664c2603336E57B271c5C0b26F421741e481",
        "kind": "unknown",
        "implementation": null,
        "admin": null,
        "beacon": null,
        "upgradeable": null,
        "slots_probed": [],
        "detail": "no RPC endpoint is configured, so no slot could be read"
      }
    },
    "token": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "has_code": null,
      "code_size": null,
      "symbol": null,
      "decimals": null,
      "total_supply": null,
      "is_erc721": null,
      "detail": "no RPC configured, so code presence could not be read; no RPC configured, so token metadata could not be read"
    },
    "denylist_hits": [],
    "unresolved": [
      "The allowance 0x2626664c2603336E57B271c5C0b26F421741e481 already holds could not be read: no RPC endpoint is configured, so the allowance this spender already holds could not be read. Whether this request adds to an existing allowance or replaces one is therefore unknown.",
      "Whether 0x2626664c2603336E57B271c5C0b26F421741e481 is a contract or an account could not be determined: no RPC endpoint is configured, so it is unknown whether the spender has code.",
      "The code that would execute on 0x2626664c2603336E57B271c5C0b26F421741e481's behalf could not be resolved: no RPC endpoint is configured, so no slot could be read. An allowance to a contract whose executing code is unknown is an allowance to unknown code."
    ],
    "rpc": {
      "configured": false,
      "reachable": null,
      "endpoints": []
    }
  },
  "policy_version": "2026-09-19",
  "request_hash": "sha256:a88cb1eea90d411505068349493a5cf35a1f2b46f4cbb4185330ffd4094c65fb",
  "data_versions": {
    "denylist": "2026-08-03.1",
    "abi_packs": "2026-08-03.1",
    "signature_index": "2026-08-03.1",
    "policy": "2026-09-19",
    "chain": "eip155:8453",
    "allowance_sentinels": "4"
  },
  "warnings": []
}
```

## Result contract

Every response is the shared portfolio envelope: `ok`, `verdict`, `confidence`, `risk_codes`,
`evidence`, `result`, `policy_version`, `request_hash`, `data_versions`, `warnings`.

`verdict: "unknown"` is a real answer, not a failure. It means the service could not determine
the result and says why in `evidence`. It is never silently reported as a safe or clean outcome.

## Service level

- Target P50: 600 ms
- Target P95: 2000 ms

## Data handling

- Caller content is processed transiently and never retained.
- No training on customer content.
- Subprocessors: base-rpc.publicnode.com, base.gateway.tenderly.co, mainnet.base.org

## Machine-readable surfaces

- https://allowance.schemasure.com/openapi.json
- https://allowance.schemasure.com/.well-known/x402.json
- https://allowance.schemasure.com/.well-known/pricing.json
- https://allowance.schemasure.com/.well-known/benchmarks.json
- https://allowance.schemasure.com/.well-known/data-handling.json
- https://allowance.schemasure.com/apis.json
- https://allowance.schemasure.com/SKILL.md