@nonagon-link/mcp 0.3.1 → 0.3.3

package/README.md

@@ -54,7 +54,7 @@ Use `currency` together with `maxPrice` to set a budget; the tool rejects an unq
 
 1. Set `NONAGON_EVM_PRIVATE_KEY` to a **dedicated EVM wallet with a small balance** (`0x` + 64 hex). It is only used to sign typed data (the signer cannot sign transactions). It works only when `NONAGON_NETWORK` is Solana mainnet or devnet, which selects the EVM networks in the table above; with any other network the server refuses to start.
 2. Set `NONAGON_EVM_PAY_TO` to the NONAGON LINK EVM treasury (see [NONAGON LINK payees](#nonagon-link-payees) — never copy it from an untrusted 402). Unset = every EVM payment is refused.
-3. Pass `maxPaymentJpy` to `pay_and_call` (at most 4 decimals). Without it a yen 402 is not signed: the tool returns `PAYMENT_EXCEEDS_LIMIT` with `max: null` and the required amount. The ceiling is 100 by default; raise it with `MCP_MAX_PAYMENT_JPY_CAP` (100–1000; below 100 the server does not start). Polygon JPYC listings start at 10 and Ethereum JPYC listings start at 300, so Ethereum ones need a cap of 300 or more.
+3. Pass `maxPaymentJpy` to `pay_and_call` (at most 4 decimals). Without it a yen 402 is not signed: the tool returns `PAYMENT_EXCEEDS_LIMIT` with `max: null` and the required amount. The ceiling is 100 by default; raise it with `MCP_MAX_PAYMENT_JPY_CAP` (100–1000; below 100 the server does not start). Polygon JPYC listings start at 1 and Ethereum JPYC listings start at 300, so Ethereum ones need a cap of 300 or more. Payments from 1 Polygon JPYC are supported from 0.3.2; 0.3.1 and earlier require at least 10.
 
 Before signing, the server checks that the 402's network, asset (the pinned JPYC contract), EIP-712 domain, amount range, `exact` + `eip3009` method, `maxTimeoutSeconds` (≤ 300) and `payTo` all match; otherwise it returns `PAYMENT_REQUIREMENT_REJECTED` without signing. Without an EVM wallet a JPYC listing returns `EVM_WALLET_NOT_CONFIGURED`. EVM USDC is covered in [Paying in EVM USDC](#paying-in-evm-usdc).
 
@@ -80,7 +80,7 @@ Three settings are needed, plus one argument per call:
 3. `MCP_MAX_PAYMENT_EVM_USDC_CAP` — the most this server may pay per EVM USDC call, written in decimal notation with at most 6 fractional digits. The allowed range comes from the pinned USDC price range of this server's network family (2–10 USDC today). Unset or empty = EVM USDC is never paid. In the `.mcpb` settings this is "EVM USDC payment cap".
 4. Pass `maxPaymentEvmUsdc` (USDC, at most 6 decimals, at most the cap) to `pay_and_call`. `maxPaymentUsdc` applies to Solana USDC only and is never used for EVM USDC.
 
-| Situation | Response (`paymentStatus: "not_paid"`, nothing signed) |
+| Situation | Response (`paymentStatus: "not_paid"`, `paymentSignatureSent:false` for these pre-signing errors) |
 |---|---|
 | Cap not set | `EVM_NOT_SUPPORTED` with `reason: "evm_usdc_not_enabled"` and a hint naming the settings (only when setting them would make the 402 payable) |
 | Cap set, no EVM wallet | `EVM_WALLET_NOT_CONFIGURED` with `currency: "USDC"` |
@@ -97,11 +97,26 @@ The cap is checked again right before signing, so a call that bypasses the tool'
 
 ### Payment status
 
+GET listings take query (an object of strings, finite numbers or booleans); POST takes body (any JSON object / array / scalar / null). Map search_listings httpMethod to method. GET body, nonempty POST query, duplicate decoded keys and collisions with existing URL keys are rejected before any request; POST query:{} is treated as omitted. Existing URL encoding is preserved; query is limited to 64 parameters and 4096 serialized characters including existing values. Example: {"method":"GET","query":{"query":"日本語 & + %","page":0,"include":false}}. Only an unsigned GET402 whose final URL has zero query parameters is checked against an available queryParams schema before signing. If schema is absent, invalid, unsupported or over budget, validation is skipped and the existing payment policy still applies; payment proceeds as before. Nonempty queries use the gateway validation, including page-size clamping.
+
+not_paid means the MCP can determine that payment was not executed. Every executed tool result includes boolean paymentSignatureSent; not_paid is not synonymous with unsigned. Classifying a signed GET422 as not_paid requires NONAGON_LINK_BASE_URL to be configured with an official (nnglink.ai / *.nnglink.ai) or local (localhost / 127.0.0.1) host, the same origin, the exact /api/proxy/{providerSlug}/{listingSlug} route, a complete JSON body within 8 KiB with code SCHEMA_VALIDATION_FAILED / QUERY_TOO_LARGE / SCHEMA_UNSUPPORTED, and no PAYMENT-RESPONSE, X-PAYMENT-RESPONSE (including the saved receipt) or X-Proxy-Payment-Id. This is the configured gateway's rejection before payment execution; correct query and retry. For EVM retain authorization (network / asset / from / nonce / validBefore): it remains valid until validBefore. A signed not_paid result does not independently prove on-chain non-execution. Other signed 422 responses and communication failures retain paid / unknown according to the receipt; on unknown do not retry automatically and check authorizationState(from, nonce).
+
+NONAGON LINK can reject an unsigned request before issuing a nonce: payment-option policy is checked first (`409 PAYMENT_OPTION_DISABLED` / `503 PAYMENT_OPTIONS_UNAVAILABLE`), then EVM native readiness. Gas uses POL on Polygon or ETH on Ethereum / Base, separately from USDC / JPYC. A readiness snapshot does not reserve a USD budget or guarantee a later settlement.
+
+| HTTP | Code | Fixed message |
+|---|---|---|
+| 503 | `EVM_NATIVE_BALANCE_INSUFFICIENT` | Native gas balance is insufficient |
+| 503 | `EVM_NATIVE_READINESS_UNAVAILABLE` | Native gas readiness is unavailable |
+| 503 | `EVM_GAS_LIMIT_EXCEEDED` | Estimated gas exceeds the supported limit |
+| 503 | `EVM_TRANSACTION_ESTIMATE_UNAVAILABLE` | Gas estimation is unavailable |
+
+Existing `GAS_LIMIT_EXCEEDED` is the USD per-transaction cap, distinct from the EVM gas quantity limit. `GAS_ESTIMATE_UNAVAILABLE`, `DAILY_GAS_CAP`, `GAS_BUDGET_UNAVAILABLE`, `TX_TIMEOUT`, `TX_FAILED` and `EVM_SETTLE_FAILED` remain. The MCP classifies a request that sent no signed payment as `not_paid`; after submission only the configured gateway pre-payment GET422 contract described below can be classified as not_paid. These 503 errors retain the existing receipt-based classification.
+
 | `paymentStatus` | Meaning | What to do |
 |---|---|---|
-| `not_paid` | No payment was sent (rejected 402, limit exceeded, not configured, error before signing) | Fix the cause and retry |
+| `not_paid` | MCP can determine payment was not executed (including a configured gateway pre-payment query rejection after signing) | Fix the cause and retry |
 | `paid` | The paid request's response carried a successful receipt (even if the API itself then returned an error) | Retrying is a new payment |
-| `unknown` | A signed payment was sent but the result is not confirmed (timeout, connection loss, error response, missing receipt). The response body is **not** trusted — the host could claim anything | **Do not retry automatically** (a retry signs a new authorization and can pay twice). For EVM payments (JPYC and EVM USDC) the response includes `authorization` (`network`, `asset`, `from`, `nonce`, `validBefore`): call `authorizationState(from, nonce)` on the token contract. It can never execute only after `validBefore` has passed and `authorizationState` is `false`. `reportedTransaction`, if any, is the host's unverified claim |
+| `unknown` | A signed payment was sent but the result is not confirmed (timeout, connection loss, error response, missing receipt). The response body is **not** trusted — the host could claim anything | **Do not retry automatically** (a retry signs a new authorization and can pay twice). For EVM payments (JPYC and EVM USDC) the response includes `authorization` (`network`, `asset`, `from`, `nonce`, `validBefore`): call `authorizationState(from, nonce)` on the token contract. It can never execute only after `validBefore` has passed and `authorizationState` is `false`. `reportedTransaction`, if any, is the host's unverified claim: independently check its receipt on the saved network and require `transactionHash` to equal the requested hash before reading status. A missing / different-hash receipt does not prove non-payment. Keep the original authorization lookup fields and check again after `validBefore`; a false state before expiry is insufficient. Do not reuse the authorization or automatically create another payment |
 
 Payments made with the EVM wallet appear in `get_payment_history` / `get_spending` as the `ethereum` wallet. For an EVM payment, **a missing history row does not prove the authorization was not executed** (the server may not have recorded a failed payment, and anyone holding the authorization can execute it): when `paymentStatus` is `unknown`, check `authorizationState` as described above instead of retrying after looking at the history.
 
@@ -114,7 +129,7 @@ Add to your MCP client config (e.g. `.claude/settings.json` or `claude_desktop_c
   "mcpServers": {
     "nonagon-link": {
       "command": "npx",
-      "args": ["-y", "--ignore-scripts", "@nonagon-link/mcp@0.3.1"],
+      "args": ["-y", "--ignore-scripts", "@nonagon-link/mcp@0.3.3"],
       "env": {
         "NONAGON_PRIVATE_KEY": "<Base58 Solana secret key>",
         "NONAGON_LINK_BASE_URL": "https://api.nnglink.ai",
@@ -125,7 +140,7 @@ Add to your MCP client config (e.g. `.claude/settings.json` or `claude_desktop_c
 }
 ```
 
-> **Always pin an exact version** (`@nonagon-link/mcp@0.3.1`). Never use an unversioned `@nonagon-link/mcp` — your private key is passed to the process environment, so an unpinned install would expose it to whatever the latest published version is. `--ignore-scripts` additionally prevents dependency install scripts from running with your environment.
+> **Always pin an exact version** (`@nonagon-link/mcp@0.3.3`). Never use an unversioned `@nonagon-link/mcp` — your private key is passed to the process environment, so an unpinned install would expose it to whatever the latest published version is. `--ignore-scripts` additionally prevents dependency install scripts from running with your environment.
 >
 > **Set `NONAGON_PAY_TO`** to the NONAGON LINK Solana platform wallet (see [NONAGON LINK payees](#nonagon-link-payees)) — do not copy `payTo` from an untrusted 402. Unset = every **Solana USDC** payment is refused. EVM payments (JPYC, EVM USDC) are allowed separately by `NONAGON_EVM_PAY_TO`; unset, every EVM payment is refused.
 
@@ -143,7 +158,7 @@ The current values are also listed at https://nnglink.ai/docs/mcp.
 For stricter isolation, install once and reference the binary directly:
 
 ```bash
-npm install -g @nonagon-link/mcp@0.3.1
+npm install -g @nonagon-link/mcp@0.3.3
 ```
 
 ```json