VickyXAI · Nov 5, 2026 · Nov 5, 2026 · Nov 5, 2026 · Nov 5, 2026 · Nov 5, 2026
diff --git a/README.md b/README.md
@@ -50,7 +50,7 @@ client = OpenAI(
     base_url="https://api.blockrun.ai/v1",
 )
 response = client.chat.completions.create(
-    model="openai/gpt-4.1-nano",
+    model="openai/gpt-4.1-mini",
     messages=[{"role": "user", "content": "Hello!"}],
 )
 print(response.choices[0].message.content)
@@ -62,14 +62,14 @@ The BlockRun SDK updates extend account authentication to chat/streaming, media,
 from blockrun_llm import LLMClient
 
 with LLMClient() as client:  # Reads BLOCKRUN_API_KEY
-    print(client.chat("openai/gpt-4.1-nano", "Hello!"))
+    print(client.chat("openai/gpt-4.1-mini", "Hello!"))
 ```
 
 ```typescript
 import { LLMClient } from '@blockrun/llm';
 
 const client = new LLMClient(); // Reads BLOCKRUN_API_KEY
-console.log(await client.chat('openai/gpt-4.1-nano', 'Hello!'));
+console.log(await client.chat('openai/gpt-4.1-mini', 'Hello!'));
 ```
 
 For wallet billing, start with **Solana** at [sol.blockrun.ai](https://sol.blockrun.ai), followed by **Base** at [blockrun.ai](https://blockrun.ai). Existing wallet users can keep their selected chain. Account credits and wallet USDC balances are separate; an account credit error should not silently switch payment modes.

diff --git a/docs/README.md b/docs/README.md
@@ -7,7 +7,7 @@ description: BlockRun is the routing and payment layer for AI agents — one end
 
 **Agents that pay, spend, and trade.**
 
-BlockRun is economic infrastructure for the agent era. AI agents discover services, pay in USDC over the [x402 protocol](x402/how-it-works.md), and execute autonomously — **no API keys, no subscriptions, no credit card.** One funded wallet unlocks 92 LLMs, media generation, real-time data, and on-chain execution.
+BlockRun is economic infrastructure for the agent era. AI agents discover services, pay in USDC over the [x402 protocol](x402/how-it-works.md), and execute autonomously — **no API keys, no subscriptions, no credit card.** One funded wallet unlocks 91 LLMs, media generation, real-time data, and on-chain execution.
 
 :::tip{title="In a hurry?"}
 Jump to the [5-Minute Quickstart](getting-started/quickstart.md) and make your first paid call.
@@ -38,7 +38,7 @@ Pick the path that matches how you work.
 ::::cards
 
 :::card{title="I want an autonomous agent" href="products/franklin.md" icon="Rocket"}
-Franklin — the AI agent with a wallet. Writes code and spends USDC across 92 models and paid APIs. Free to start.
+Franklin — the AI agent with a wallet. Writes code and spends USDC across 91 models and paid APIs. Free to start.
 :::
 
 :::card{title="I use Claude Code / Cursor" href="getting-started/quickstart.md" icon="Terminal"}
@@ -62,7 +62,7 @@ Four product families, one payment layer.
 ::::cards
 
 :::card{title="Intelligence" href="products/intelligence/overview.md" icon="Brain"}
-92 LLMs (GPT, Claude, Gemini, DeepSeek, Grok, Kimi, Llama) through one OpenAI-compatible API. Pay per request.
+91 LLMs (GPT, Claude, Gemini, DeepSeek, Grok, Kimi, Llama) through one OpenAI-compatible API. Pay per request.
 :::
 
 :::card{title="Routing" href="products/routing/clawrouter.md" icon="Route"}

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -62,6 +62,7 @@
 * [Virtual Portrait Enrollment](api-reference/virtual-portrait.md)
 * [RealFace Enrollment](api-reference/realface.md)
 * [Music Generation](api-reference/music-generation.md)
+* [Agent wallet integration and result recovery](api-reference/agent-wallet-integration.md)
 * [Text-to-Speech & Sound Effects](api-reference/text-to-speech.md)
 * [Search](api-reference/search.md)
 * [Decisions (Typed Judgments)](api-reference/decisions.md)

diff --git a/docs/api-reference/agent-wallet-integration.md b/docs/api-reference/agent-wallet-integration.md
@@ -0,0 +1,61 @@
+---
+title: Agent wallet integration and result recovery
+description: Avoid duplicate submissions, schema failures and truncated paid results when using BlockRun through an agent wallet.
+---
+
+# Agent wallet integration and result recovery
+
+This page applies to the Base and Solana x402 gateways, not the separate MPP gateway. A successful on-chain payment, a successful HTTP response and a result delivered to the agent are separate observations; record all three.
+
+## Long requests and lost responses
+
+Handle HTTP `202` and retain `id`, `poll_url`, the original signed credential and any receipt before retrying. Music submits hand off after about ten seconds. Search keeps the connection open until the result is ready; send `Prefer: respond-async` to get `202` with `id` and `poll_url` after about ten seconds instead. Either way, an exact search credential recovers the original task pointer for 24 hours. Retrieve the result and receipt through `GET /api/v1/search/{id}` using a fresh wallet message proof from the same wallet (Base also accepts an unused payment authorization); the poll never settles another payment. A historical payment credential or job URL alone grants no content access.
+
+Replaying the original credential returns the original task pointer even after payment has settled. Search returns `409` with code `SEARCH_ALREADY_SUBMITTED` unless the caller sends `Prefer: respond-async`, which opts into `202`; music and images use `202`. Poll that task rather than paying for another submission. Solana image generation and editing persist an owner-bound job and canonical credential digest before charging, and recover the pointer before simulating an expired or spent transaction. A recovered pointer does not authorize delivery: the poll withholds images while the original POST payment is pending or definitely refused. An unknown settlement outcome may already have charged, so check the original receipt before authorizing another payment. Batch and charge-on-completion jobs keep their existing completion-payment flow. A search that recorded no result ends differently on each gateway: on Base the poll returns `502` with code `RESULT_UNAVAILABLE` after about 15 minutes, and on Solana it returns `200` with `status: "failed"` after about an hour. Either way, check the original receipt before authorizing another. A new authorization starts a separate billable submission. Do not treat every `402`, timeout or missing client response as proof that nothing settled: inspect the original receipt or ledger first.
+
+Solana transactions have a limited recent-blockhash lifetime. An already paid music, image or search task should be located through its original submission binding, then polled. Re-simulating the old transaction is unnecessary. A genuinely new payment requires a newly constructed transaction with a current blockhash.
+
+For Solana search, sign `blockrun-poll:v1:search:<id>:<unix seconds>` as a UTF-8 ed25519 message. Send the public key as `x-poll-wallet`, timestamp as `x-poll-timestamp` and base58 signature as `x-poll-signature`. This is the only way to read a Solana search result: a payment-only wallet that cannot sign messages gets `401`, so it can recover the task pointer but not the content. The original submit credential retrieves only the pointer; it is not a permanent read token. Polling never simulates or settles a transaction. These recovery records are created by the current submit flow; a historical lost response without a saved job cannot be reconstructed retroactively.
+
+## Response contracts and size limits
+
+Search citations are `{ "url": "https://example.org", "title": "Example" }` objects. Image editing returns short media URLs. On Base, polling an older paid image job repairs a missing backup from its stored image without another generation or charge.
+
+On Base, DeFiLlama accepts `?format=compact&limit=25` and optionally `fields=name,slug,tvl`. Compact responses stay below 256 KiB. A selection that cannot fit returns `413` without a charge; a nonempty page whose selected fields produce only empty objects returns `400` without a charge. An actually empty page remains valid. List responses include `pagination.next_offset`, which is `null` on the last page; detail responses have `pagination: null`. Protocol detail omits large historical arrays by default in compact mode. Each page is a separately priced request. Raw passthrough is still available; a client with a response cap may truncate it even when the gateway returned the complete data. The Solana gateway has no DeFiLlama route.
+
+## Recovery windows and stored data
+
+The application limits search-result and media-submission recovery to 24 hours. Recovery records use a separate 2-day lifecycle eligibility rule; generated media and media-job records retain their existing 30-day rule. Lifecycle deletion runs asynchronously, and bucket soft delete or versioning can retain copies afterward. A read-window limit is not a promise of immediate physical deletion. Operators must apply and verify the bucket rules before deploying the recovery flow.
+
+## Media formats, exact prices and funding metadata
+
+Generated image MIME types and extensions follow the encoded bytes rather than an upstream label. A JPEG must be served as `image/jpeg` with a `.jpg` URL, even when a provider labels it PNG. Existing historical objects keep their original URLs; correction applies when an asset is backed up or generated through the current flow.
+
+USDC amounts use six decimal places. Solana quotes and displayed image-result prices derive from the same integer micro-USDC amount. Floating-point noise such as `0.05 * 1.05` must not add an extra micro-USDC; a genuine fractional micro-USDC still rounds up.
+
+Solana batch funding challenges identify the configured public resource URL, not an internal or forwarded host.
+
+## Discover supported requests before paying
+
+- Read the current model list. `openai/gpt-4.1-nano` was retired by OpenAI on October 23, 2026. `openai/gpt-4.1-mini` is available, though OpenAI has scheduled its dated snapshot for removal on January 14, 2027.
+- Music costs **$0.20 per track including the transaction fee**. Read the live `402` quote before signing.
+- FX and commodity spot prices are available, but their free historical-bar source is unsupported (`501`). Equity symbol lists may return `available: false`; a listed symbol is not a promise of price coverage.
+- UMA markets requires `state`. Kalshi trades requires `ticker` or `event_ticker`.
+- Smart activity requires at least one meaningful threshold: PnL of 5000, ROI of 0.15, 100 trades, or volume of 10000. Per-market smart money uses a PnL threshold of 1000; the alternative thresholds remain valid.
+- The Base gateway rejects requests missing these market parameters before payment. The Solana gateway does not pre-check them, so send them yourself.
+- On Base, Binance minute candles default to the last hour when both timestamps are omitted. Elsewhere, send a short time range. Unix timestamps are seconds.
+- Register stable submit/discovery endpoints. A historical `/audio/generations/{id}` URL is a particular task, not a reusable public API entry. Unauthorized access to an old job says nothing about whether new music generation works.
+
+## Free wallet authentication
+
+`POST /api/v1/onramp/token` and `POST /api/v1/phone/numbers/release` support wallet messages instead of zero-value payments: EIP-191 on Base (hex signature), ed25519 on Solana (base58 signature). Send the owner address in `X-Wallet-Address` to obtain the message in a `401` response, sign it locally, and resend the identical body with `X-Wallet-Address`, `X-Wallet-Timestamp` and `X-Wallet-Signature`. The proof binds origin, method, path, wallet, body hash and timestamp, expires after five minutes and can be used once. The Onramp destination must match the signer and number release still requires ownership. GET returns a message template with HTTP 401, not an x402 quote. POST returns the exact body-bound message. No transaction or payment is necessary.
+
+A payment-only wallet tool that cannot sign messages needs client support for this flow. Increasing the fee is not a substitute for an identity proof on a free operation.
+
+## Distinguish unresolved client state from merchant defects
+
+Endpoint-registration throttling is a limit inside the wallet service, not on BlockRun. Reuse registrations and honor retry/backoff guidance instead of creating a new registration for every job URL.
+
+A `pending_confirmation` amount can be a budget hold. It is not evidence of a second on-chain charge. Reconcile wallet payment IDs, original merchant job IDs and chain transactions before refunding or submitting another payment. A pending task that later completes is not a permanent service outage.
+
+If a facilitator rejects a payment payload's schema, capture redacted field names and versions for diagnosis, never private keys or complete signed credentials.
diff --git a/docs/api-reference/chat-completions.md b/docs/api-reference/chat-completions.md
@@ -1,6 +1,6 @@
 ---
 title: Chat Completions
-description: OpenAI-compatible Chat Completions endpoint for 92 LLMs, paid per request in USDC over x402 — no API keys, no subscriptions.
+description: OpenAI-compatible Chat Completions endpoint for 91 LLMs, paid per request in USDC over x402 — no API keys, no subscriptions.
 ---
 
 # Chat Completions
@@ -371,7 +371,7 @@ console.log(result.choices[0].message.content);
 ::::cards
 
 :::card{title="Browse all models" href="models.md" icon="Brain"}
-92 chat models with live pricing — pick the right model and ID for your call.
+91 chat models with live pricing — pick the right model and ID for your call.
 :::
 
 :::card{title="Error handling" href="errors.md" icon="Code"}

diff --git a/docs/api-reference/exa-search.md b/docs/api-reference/exa-search.md
@@ -393,7 +393,7 @@ Real-time web and news search via Grok Live Search.
 :::
 
 :::card{title="Chat Completions" href="chat-completions.md" icon="Brain"}
-Feed grounded search results into any of 92 LLMs for synthesis.
+Feed grounded search results into any of 91 LLMs for synthesis.
 :::
 
 :::card{title="Error handling" href="errors.md" icon="Code"}

diff --git a/docs/api-reference/models.md b/docs/api-reference/models.md
@@ -137,7 +137,6 @@ Released 2026-04-23 — first fully retrained base since GPT-4.5.
 | `openai/gpt-4.1` | GPT-4.1 | $2.00/M | $8.00/M | 128K |
 | `openai/gpt-4.1-mini` | GPT-4.1 Mini | $0.40/M | $1.60/M | 128K |
 | `openai/gpt-4o-mini` | GPT-4o Mini | $0.15/M | $0.60/M | 128K |
-| `openai/gpt-4.1-nano` | GPT-4.1 Nano | $0.10/M | $0.40/M | 128K |
 
 ### Anthropic Claude
 
@@ -405,3 +404,5 @@ Route each prompt to the cheapest model that can handle it, automatically.
 :::
 
 ::::
+
+`openai/gpt-4.1-nano` was retired by OpenAI on October 23, 2026 and is no longer advertised as available. `openai/gpt-4.1-mini` is available, though OpenAI has scheduled its dated snapshot for removal on January 14, 2027.