chain-insights 0.3.5 → 0.3.7

package/README.md

@@ -19,7 +19,7 @@ MCP endpoint for development; hosted endpoints are set explicitly with
 | `trace_victim_funds` | Trace victim/source funds forward to exchange deposit candidates |
 | `trace_deposit_sources` | Trace backward from suspected deposit/cashout addresses to upstream sources and convergence |
 | `trace_suspect_funds` | Trace suspected scammer, mule, operator, or laundering-ring funds forward to cashout topology |
-| `usage_status` | Check the caller's public free graph query quota for today |
+| `usage_status` | Check the caller's daily free-tier graph query allowance |
 | `graph_query` | Run one read-only GQL/Cypher query against a GraphRAG MCP graph layer |
 | `graph_query_batch` | Run related read-only graph queries as one MCP call |
 
@@ -117,11 +117,14 @@ If network or tool discovery fails, check the endpoint and access mode first.
 The CLI can still initialize workspaces and manage cases without a reachable
 GraphRAG MCP endpoint.
 
-Hosted GraphRAG MCP lets new users try `graph_query` with a small public free
-quota before setting up paid access. The default public free graph_query quota
-is 10 execution seconds per IP per UTC day. Use `usage_status` to see the
-current caller quota. When the free quota is exhausted, prepare a wallet or use
-an invited tester access key and retry.
+Hosted GraphRAG MCP includes a small public free tier for `graph_query` before
+paid access is required. The default public free tier is 10 execution seconds
+per IP per UTC day. Use `usage_status` to see the current caller allowance.
+Prepared wallet users receive the daily free tier first, then paid access
+continues automatically after the allowance is exhausted.
+If you do not have a prepared wallet yet, use bounded single `graph_query`
+calls within the free tier, then prepare a wallet or use an invited tester
+access key when the allowance is exhausted.
 
 Open a case and run a small investigation:
 
@@ -159,12 +162,12 @@ The export writes Markdown notes, `manifest.chain-insights.json`,
 for Codex, Claude Code, and ChatGPT under `published/<case-slug>/`.
 
 Private exports may include full addresses. Use `--mode partner` for controlled
-handoff after review. Use `--mode public` only for shareable demos; public mode
+handoff after review. Use `--mode public` only for shareable examples; public mode
 aliases addresses and removes secrets by default. Vault workflow guidance lives
 in [Obsidian vault workflow](docs/obsidian-vault.md); export bundle details
 live in [Knowledge exports](docs/knowledge-exports.md).
 
-## Demo
+## Examples
 
 Run a direct live topology query:
 
@@ -182,6 +185,10 @@ cia mcp call graph_query_batch \
   'queries=[{"id":"count","query":"USE live_topology MATCH (n) RETURN count(n) AS count LIMIT 1"},{"id":"archive_flows","query":"USE archive_topology MATCH (src:Address)-[f:FLOWS_TO]->(dst:Address) RETURN f.period_granularity AS granularity, src.address AS source, dst.address AS target LIMIT 3"},{"id":"facts_sample","query":"USE facts MATCH (a:Address)-[:HAS_FEATURE]->(f:AddressFeature) RETURN a.address AS address, f.sent_count AS sent_count LIMIT 3"}]'
 ```
 
+For no-wallet public free-tier usage, prefer the single-query example first.
+Batch calls reserve worst-case execution time and can ask for paid access even
+when a small free allowance remains.
+
 Run suspect topology without requiring an incident timestamp:
 
 ```bash

package/docs/graph-tools.md

@@ -14,7 +14,7 @@ The GraphRAG MCP public graph surface is intentionally small:
 
 | Tool | Purpose |
 | --- | --- |
-| `usage_status` | Return the caller's public free graph_query quota for the current UTC day |
+| `usage_status` | Return the caller's daily free-tier graph_query allowance for the current UTC day |
 | `graph_query` | Run one read-only GQL/Cypher query through the universal graph endpoint |
 | `graph_query_batch` | Run related read-only graph-language queries as one MCP call |
 
@@ -31,14 +31,18 @@ GraphRAG MCP endpoint.
 - Use `USE archive_topology` for historical topology.
 - Use `USE facts` for labels, features, risk scores, assets, and enrichment.
 - Use `usage_status` before public hosted reads when you need the caller's
-  remaining free quota.
-- Hosted endpoints can expose a public free graph_query quota. The default is
-  10 execution seconds per IP per UTC day.
+  remaining free-tier allowance.
+- Hosted endpoints can expose a public free tier for graph_query. The default
+  is 10 execution seconds per IP per UTC day.
+- Prepared wallet users receive the daily free tier first; after it is used,
+  x402 payment continues automatically from the configured wallet.
 - Use explicit LIMIT and pagination in your query when you want bounded result
   sets.
 - The GraphRAG MCP server does not append `LIMIT`; Chain Insights recipes own
   their own limits and pagination.
-- Use `graph_query_batch` for related reads that should share one paid call.
+- Use single bounded `graph_query` calls for public no-wallet free-tier usage. Use
+  `graph_query_batch` for related reads that should share one paid call; public
+  free-tier access does not include batches.
 - `per_query_timeout_seconds` is optional and capped at `10` by default.
 - Returned rows live in `structuredContent.facts`.
 
@@ -74,6 +78,10 @@ chain-insights mcp call graph_query_batch \
   'queries=[{"id":"count","query":"USE live_topology MATCH (n) RETURN count(n) AS count LIMIT 1"},{"id":"archive_flows","query":"USE archive_topology MATCH (src:Address)-[f:FLOWS_TO]->(dst:Address) RETURN f.period_granularity AS granularity, src.address AS source, dst.address AS target LIMIT 3"}]'
 ```
 
+Batch calls reserve worst-case execution time from their timeout settings. On
+public hosted endpoints, they can ask for paid x402 access even when a small
+free-tier allowance remains.
+
 Batch result facts include:
 
 ```json

package/docs/mcp-proxy.md

@@ -140,7 +140,7 @@ chain-insights access-key set ci_test_REDACTED --endpoint https://staging-mcp.ch
 chain-insights access-key status
 ```
 
-Public free graph usage:
+Daily free-tier graph usage:
 
 ```bash
 chain-insights mcp call usage_status
@@ -150,12 +150,23 @@ chain-insights mcp call graph_query \
 ```
 
 Hosted GraphRAG MCP can allow anonymous `graph_query` calls before wallet
-setup. The default public free graph_query quota is 10 execution seconds per IP
-per UTC day, reset on the UTC calendar day. `usage_status` returns only the
-current caller's quota status. Public free access does not include
-`graph_query_batch`; use a tester access key or paid x402 mode for regular
-usage and batches. Use explicit LIMIT and pagination in your query when you
-want bounded result sets.
+setup. The default public free tier is 10 execution seconds per IP per UTC day,
+reset on the UTC calendar day. `usage_status` returns only the current caller's
+allowance status. Wallet users receive the same daily free tier first; after it
+is exhausted, x402 payment continues automatically when `wallet ready` reports
+ready.
+
+The daily free tier is intended for bounded single `graph_query` calls. It does
+not include `graph_query_batch`; use a tester access key or paid x402 mode for
+regular usage and batches. Use explicit LIMIT and pagination in your query when
+you want bounded result sets.
+
+Staging UAT on 2026-05-31 showed the 10-second free tier was enough for exact
+Bittensor address checks, sample address reads, sample flow reads, and the
+free-to-paid handoff. The tested address
+`5EkTMF1noWnWupGxQqtPczW2FFB7ktdVwjaZ22Cam54U93Xx` returned no indexed live or
+archive rows on staging, but bounded sample reads still returned Bittensor
+topology data inside the same daily allowance.
 
 For custom graph reads, install the shipped `chain-insights-cypher` skill. Its
 Memgraph examples reference distinguishes staging-tested GraphRAG MCP query

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chain-insights",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "AML investigation CLI and MCP proxy for blockchain risk, fund-flow tracing, case reports, and GraphRAG MCP access",
   "homepage": "https://chain-insights.ai",
   "repository": {