Assay: settlement verification

Check whether a crypto payment really settled and how much was ACTUALLY delivered, which is often not the amount the transaction claims. Use this before crediting anyone for an incoming payment. Returns `delivered` (what truly moved), `claimed` (what the transaction says), `mismatch` (true when they disagree), and `warnings` naming the specific trap with a remedy. `ok` is true ONLY when the payment is final and meets everything you asserted in `expect`; anything uncertain returns ok:false, so it is safe to gate a credit on `ok`. Chains: xrp, hedera, algorand, solana, ethereum, base, arbitrum, optimism, polygon, bnb, avalanche, linea, scroll, zksync, blast, mantle, celo, gnosis, bitcoin, litecoin. Pass `expect` whenever you can. Without it this reports what happened; with it, it tells you whether to pay. Read only: this never moves funds and never holds keys.

{
  "type": "object",
  "properties": {
    "chain": {
      "type": "string",
      "description": "Chain id. One of: xrp, hedera, algorand, solana, ethereum, base, arbitrum, optimism, polygon, bnb, avalanche, linea, scroll, zksync, blast, mantle, celo, gnosis, bitcoin, litecoin. Common aliases work too (eth, btc, matic, bsc, avax, sol, xrpl). Not needed for sandbox: references."
    },
    "ref": {
      "type": "string",
      "description": "The transaction hash or id. EVM: 0x + 64 hex. XRP: 64 hex. Solana: base58 signature. Bitcoin: 64 hex. Hedera: 0.0.1234-1700000000-123456789. Algorand: 52 base32 chars. Or a sandbox case like sandbox:xrp_partial_payment."
    },
    "expect": {
      "type": "object",
      "description": "What you believe should be true. Supplying this is what lets `ok` mean anything.",
      "properties": {
        "amount": {
          "type": "string",
          "description": "Minimum acceptable amount in the asset's SMALLEST units, as a string (1 USDC = \"1000000\"). Compared against DELIVERED, never against the claimed amount."
        },
        "asset": {
          "type": "string",
          "description": "Expected asset symbol, e.g. USDC. Symbols are not unique, so prefer assetId."
        },
        "assetId": {
          "type": "string",
          "description": "Expected contract address or canonical token id. The reliable way to avoid being paid in a counterfeit token with the right symbol."
        },
        "to": {
          "type": "string",
          "description": "The address that should have received it. Required on Bitcoin and Litecoin to get a meaningful delivered amount, because a UTXO transaction has many outputs and most of them may be change."
        },
        "memo": {
          "type": "string",
          "description": "Expected destination tag or memo, used to attribute a payment on a shared receiving address."
        },
        "minConfirmations": {
          "type": "integer",
          "description": "Override the chain default before treating the payment as final."
        }
      }
    },
    "rpcUrl": {
      "type": "string",
      "description": "Optional. Your own HTTPS RPC endpoint for this chain. Bypasses our rate limits entirely and usually returns faster."
    }
  },
  "required": [
    "ref"
  ]
}

List every chain this service can verify, with the confirmation depth each needs before a payment is treated as final, and how deeply it can be verified. Call this if you are unsure whether a chain is supported or what to pass as `chain`.

{
  "type": "object",
  "properties": {}
}

List every known way a blockchain payment can appear successful while being worth less than it claims, or nothing at all. Each entry explains what the chain does, what it costs you when you get it wrong, and the one-line fix. Useful when writing or reviewing code that credits users for incoming crypto payments. Every chain has its own dialect but they are all the same few lies, and the mitigation is always the same: never trust the stated amount, reconstruct what actually moved.

{
  "type": "object",
  "properties": {
    "family": {
      "type": "string",
      "description": "Optionally filter to one family: xrpl, evm, utxo, svm, hedera, algorand, or all."
    }
  }
}

Check a proposed payment against spending limits that live OUTSIDE your context, where no instruction in a prompt, a message or a web page can change them. Returns a signed allow or deny with reasons. Use this before executing any transfer on behalf of a user. It enforces velocity caps, per-action ceilings, recipient allowlists and asset allowlists. Because the rules are held server side and signed, an attacker who takes over your reasoning still cannot raise your limits. IMPORTANT: this is ADVISORY. Assay holds no keys and cannot stop a transaction. Verify the signature and enforce the decision wherever you sign. Create a policy first with the /v1/policy endpoint.

{
  "type": "object",
  "properties": {
    "policyId": {
      "type": "string",
      "description": "From creating a policy."
    },
    "policySecret": {
      "type": "string",
      "description": "The secret returned when the policy was created. Shown once, stored only as a hash."
    },
    "action": {
      "type": "object",
      "description": "The payment you are about to make.",
      "properties": {
        "type": {
          "type": "string",
          "description": "e.g. transfer. Recorded, not interpreted."
        },
        "chain": {
          "type": "string"
        },
        "to": {
          "type": "string",
          "description": "Recipient address."
        },
        "asset": {
          "type": "string",
          "description": "Symbol or contract id."
        },
        "amount": {
          "type": "string",
          "description": "Base units as a string."
        }
      }
    },
    "commit": {
      "type": "boolean",
      "description": "Default true: an allowed action counts against velocity limits. Pass false to ask 'would this be allowed' without consuming budget."
    }
  },
  "required": [
    "policyId",
    "policySecret",
    "action"
  ]
}

Practise on a payment designed to deceive you, with no money at risk. Returns a verification result shaped exactly like a real one for one of 19 adversarial cases. Decide whether you would credit it, then call check_sandbox_answer to find out whether you were right and what the mistake would have cost. Use this to test any agent or integration that handles incoming crypto payments BEFORE it handles real money.

{
  "type": "object",
  "properties": {
    "caseId": {
      "type": "string",
      "description": "Which case to run. Omit to get the list of available cases."
    }
  }
}

Score your decision on a sandbox case. Tell it whether you would have credited the payment and for how much, and it replies with whether that was correct and, if not, exactly what the error would have cost you in real units. This is the fastest way to find out whether your payment handling is actually safe.

{
  "type": "object",
  "properties": {
    "caseId": {
      "type": "string",
      "description": "The case you ran."
    },
    "credit": {
      "type": "boolean",
      "description": "Would you have credited this payment?"
    },
    "amount": {
      "type": "string",
      "description": "If crediting, how much, in the asset's smallest units."
    }
  },
  "required": [
    "caseId",
    "credit"
  ]
}