{
  "title": "ipfacts payment rules",
  "summary": "How ipfacts charges for x402-paid calls (REST /full and /threat, MCP ip_facts_full and ip_threat_check) and what each payment problem returns. ipfacts follows the x402 v2 specification, with one documented difference: an answer whose settlement is still pending is delivered. Every REST error an API client gets is application/problem+json, and a payment error's type links to its rule below.",
  "docs": "https://ipfacts.com/learn#payment-rules",
  "json": "https://api.ipfacts.com/payment-rules",
  "spec": "https://github.com/x402-foundation/x402/tree/main/specs",
  "rules": [
    {
      "id": "charged-on-success",
      "title": "You pay only for an answer you get",
      "short": "Verify, then the lookup, then settle. A lookup that fails is never settled, so it costs nothing.",
      "text": "ipfacts verifies the payment with the facilitator, runs the lookup, and settles only when the lookup succeeded. A malformed address is refused before any price is quoted, and a lookup that can't be answered (for example a threat check while the list isn't loaded) is never settled."
    },
    {
      "id": "quote",
      "title": "No payment: a 402 with the quote",
      "short": "REST: 402 + PAYMENT-REQUIRED header. MCP: isError + PaymentRequired. One offer: exact, USDC, EIP-3009.",
      "text": "A paid call without payment gets the quote. REST answers 402 with the base64 x402 v2 PaymentRequired object in the PAYMENT-REQUIRED header and a problem+json body (a browser asking for HTML gets a readable page instead). MCP answers isError with the same object in structuredContent and in content[0].text. The quote offers one way to pay: scheme exact, USDC by EIP-3009 transferWithAuthorization, the token's EIP-712 name and version in extra, and maxTimeoutSeconds 60."
    },
    {
      "id": "pay-first",
      "title": "Paying on the first request",
      "short": "GET /pricing has the exact quote (accepts): sign it and pay on the first call. REST is GET; MCP after initialize.",
      "text": "The terms a 402 quotes are also published: GET /pricing carries the exact accepts entry for /full/{ip} (accepts), for /threat/{ip} (threat.accepts) and for each paid MCP tool (paid_tools[].accepts). Sign it and send the payment with the first request; resource is optional in an x402 v2 PaymentPayload. REST paid calls are GET with PAYMENT-SIGNATURE (another method is 405). On MCP the payment rides a normal session: after initialize, the first tools/call may carry _meta[\"x402/payment\"]. While /pricing says paid: false (the free preview) no payment is needed, and one sent is ignored and never charged. Prices can change, so a payment for an old quote is refused (402) with the current one."
    },
    {
      "id": "malformed",
      "title": "A malformed payment: 400",
      "short": "A PAYMENT-SIGNATURE that isn't a valid x402 v2 PaymentPayload is 400 (MCP: isError). Nothing is charged.",
      "text": "A PAYMENT-SIGNATURE header that isn't base64 JSON of an x402 v2 PaymentPayload carrying an exact EVM authorization and a signature, or that repeats a JSON key, is answered 400 with the reason in a problem+json body and a fresh PAYMENT-REQUIRED. On MCP the same payment in _meta[\"x402/payment\"] gets isError with the quote and the reason. Nothing is charged."
    },
    {
      "id": "refused",
      "title": "A payment that doesn't fit the quote: 402",
      "short": "Any mismatch with the quote, or a facilitator refusal: 402 with the x402 error code. Nothing ran.",
      "text": "The payment must accept the quote exactly: the same scheme, network, asset, amount and payTo; the default EIP-3009 transfer (another assetTransferMethod or paymentFlow is refused); and an authorization to payTo for exactly the amount, valid now (validAfter ≤ now < validBefore). A mismatch, or a facilitator refusal such as insufficient balance or a bad signature, is a 402 with the x402 error code in PaymentRequired.error. The lookup didn't run and nothing is charged."
    },
    {
      "id": "one-call-per-signature",
      "title": "One signature pays for one call",
      "short": "One authorization buys one answer: any reuse is refused (402). Sign a new one for each call.",
      "text": "Each signed authorization pays for one call. Sent again while the first call is still running (\"payment authorization is already in use by another request\"), or after it has bought an answer, it is refused with 402; once it has settled, its EIP-3009 nonce is spent and the facilitator refuses it too. Sign a new authorization for every call."
    },
    {
      "id": "paid",
      "title": "Paid: the answer and the settlement",
      "short": "200 with the answer and the settlement (transaction hash) in PAYMENT-RESPONSE or _meta[\"x402/payment-response\"].",
      "text": "A settled call answers 200 with the facts and the x402 SettlementResponse (success, transaction hash, network, payer) in the PAYMENT-RESPONSE header. On MCP the tool result carries it in _meta[\"x402/payment-response\"]."
    },
    {
      "id": "settle-refused",
      "title": "Settlement refused: the answer is withheld",
      "short": "No answer. REST: 402 with the failed settlement in PAYMENT-RESPONSE. MCP: isError. Final: sign anew to retry.",
      "text": "If the facilitator refuses the settlement, for example because the transfer failed on chain, the answer is withheld. REST answers 402 with the failed SettlementResponse in PAYMENT-RESPONSE and a fresh PAYMENT-REQUIRED; MCP answers isError with the failed SettlementResponse in _meta[\"x402/payment-response\"]. Every refusal except settle-pending is final, and a new signed authorization may try again."
    },
    {
      "id": "settle-pending",
      "title": "Settlement pending: you get the answer",
      "short": "Sent, not yet confirmed: one settle retry, then the answer with the pending settlement and hash. Don't pay again.",
      "text": "settlement_pending means the facilitator sent the transfer but could not yet confirm it. ipfacts retries settlement once with the same signed payment, which cannot move money twice. If it is still pending, you get the answer anyway: REST 200 with the SettlementResponse (success false, errorReason settlement_pending, the transaction hash) in PAYMENT-RESPONSE; MCP a normal result with it in _meta[\"x402/payment-response\"]. The transfer normally confirms: check the hash on chain, and don't pay again for that call. This is ipfacts' one difference from the x402 specification, where only a settled payment gets 200."
    },
    {
      "id": "facilitator-down",
      "title": "Facilitator unreachable: 500",
      "short": "500 (MCP: isError), no answer. Before the lookup nothing was charged; while settling, check your nonce first.",
      "text": "If the facilitator can't be reached, or doesn't answer in time, the call fails with 500 problem+json (MCP: isError) and no answer. During verification nothing was charged. During settlement there is no transaction hash and the transfer may still happen: before paying again, check whether your authorization was used (the USDC contract's authorizationState(from, nonce) turns true). A settlement_pending without a transaction hash is treated the same way. ipfacts has no way to collect an answer later."
    },
    {
      "id": "free-preview",
      "title": "Free preview",
      "short": "While /pricing says free_preview: true, paid calls answer without payment and no 402 is sent.",
      "text": "While the paywall is waived, /pricing reports paid: false and free_preview: true, and the paid calls answer without payment. The quote and these rules apply again when the paywall is switched back on."
    }
  ]
}
