solverr-agent 0.1.0 → 0.1.1

package/README.md

@@ -128,27 +128,16 @@ claude mcp add solverr-agent \
 
 ## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/workflow.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> How a Payment Works
 
-```mermaid
-flowchart TD
-  A["Request url with the caller's method"] -->|not 402| Z[Return response]
-  A -->|402 without a readable solverr offer| Z
-  A -->|402 with solverr scheme| B{Host allowed? Trusted gateway? Live invoice?}
-  B -->|no| X[PaymentError, nothing sent]
-  B -->|yes| C[Price the invoice in USD from /tokens]
-  C --> D{Within per-payment and 24 h limits?}
-  D -->|no| X
-  D -->|yes| E[Reserve the amount in the spend log]
-  E --> F[Rank coins held: coin the business receives, same coin on another chain, stablecoins, others]
-  F --> G[POST quote with own refund address]
-  G -->|422| F
-  G --> H{Coin, refund address, deposit address, amount, deadline, limits all check out?}
-  H -->|no| X
-  H -->|yes| I[Send exact amount_in_base to deposit_address]
-  I --> J[POST deposit tx hash, poll status until paid]
-  J -->|paid| K[Send the same request with PAYMENT-SIGNATURE, up to 3 tries]
-  J -->|underpaid, refunded, failed, timeout, any other error| Y[PaymentError, fundsSent = true, invoiceId]
-  K -->|402, or still failing| Y
-```
+1. The agent requests the URL with the caller's method. When the answer is not a `402`, or is a `402` without a `solverr` offer it can read, the agent returns that response as it is.
+2. For a `402` with the `solverr` scheme, it checks that the host is allowed, the gateway is trusted and the invoice is live. If any check fails, it throws `PaymentError` and nothing is sent.
+3. It prices the invoice in USD from `/tokens` and checks the per-payment and 24-hour limits. If the price is over a limit, it throws `PaymentError` and nothing is sent.
+4. It reserves the amount in the spend log.
+5. It ranks the coins it holds: the coin the business receives first, then the same coin on another chain, then stablecoins, then the rest.
+6. It asks for a quote (`POST`) with its own refund address. A `422` sends it back to step 5 for the next coin.
+7. It checks the quote: coin, refund address, deposit address, amount, deadline and limits. If anything does not match, it throws `PaymentError` and nothing is sent.
+8. It sends exactly `amount_in_base` to `deposit_address`, reports the transaction hash (`POST` deposit) and polls the status until the invoice is paid.
+9. Once the invoice is paid, it sends the same request with `PAYMENT-SIGNATURE`, up to 3 tries.
+10. When the payment ends underpaid, refunded, failed or timed out, any other error happens, or the paid request still fails or answers `402`, it throws `PaymentError` with `fundsSent: true` and the `invoiceId`.
 
 How each chain sends the transfer, and how payments take turns:
 
@@ -196,7 +185,7 @@ npm run build -w agent
 
 ### Publish
 
-Publish `solverr-x402` before `solverr-agent`: the agent's `package.json` names the x402 version it needs (`"solverr-x402": "0.1.0"`), and npm can only install the agent once that version exists on the registry. When x402 gets a new version, set the same exact version in the agent's `dependencies` and run `npm install` in `packages/` to update the lockfile.
+Publish `solverr-x402` before `solverr-agent`: the agent's `package.json` names the x402 version it needs (`"solverr-x402": "0.1.1"`), and npm can only install the agent once that version exists on the registry. When x402 gets a new version, set the same exact version in the agent's `dependencies` and run `npm install` in `packages/` to update the lockfile.
 
 ```bash
 cd packages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solverr-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Agent wallet that pays x402 Solverr paywalls from NEAR and Base within spending limits, plus a local stdio MCP server.",
   "license": "MIT",
   "homepage": "https://github.com/forcequitx/solverr/tree/main/packages/agent#readme",
@@ -49,7 +49,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "solverr-x402": "0.1.0",
+    "solverr-x402": "0.1.1",
     "@modelcontextprotocol/server": "2.4.0",
     "near-api-js": "7.4.0",
     "undici": "8.12.4",