feat(action-providers): add The Graph provider (query subgraphs directly, pay-per-query over x402)

[PaulieB14]

Description

Adds a thegraph action provider that lets an agent query The Graph directly and pay per query over x402 from its own wallet — no API key, no signup. Three actions:

• search_subgraphs — find the best subgraph(s) for a plain-English topic
• get_subgraph_schema — list a subgraph's queryable entities + args
• query_subgraph — run a GraphQL query against a subgraph

Query prices are variable, so each paid action probes the gateway's 402 price, enforces a per-query maxPaymentUsdc cap, and only then signs and pays. Base-only; reuses the same x402 signing stack as the built-in x402 provider, so no new dependencies. Discovery + query-construction logic is ported from PayQL (Apache-2.0).

This complements #1357 (the managed graphadvocate provider) as the self-serve tier: graphadvocate = pay an agent that does the routing/querying for you (no setup); thegraph = query The Graph gateway directly and pay your own way (cheaper, more control). Fits WISHLIST → "Trading & Data".

Tests

• Unit tests: supportsNetwork, the EVM-wallet guard (rejects non-EVM before any network call), and the ported toFulltext + parseHits logic.
• tsc --noEmit clean; 5/5 tests pass locally in a matched (pnpm/lockfile) env.
• Live example-chatbot run against a funded wallet not yet done; happy to add prompt/output samples before merge.

Checklist

• Added documentation to all relevant README.md files (thegraph/README.md)
• Added a changelog entry (.changeset/thegraph-action-provider.md)

---

🤖 Generated with Claude Code

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[PaulieB14]

@murrlincoln — following up with verification (like #1357), and I pushed a fix to this branch just now.

While testing end-to-end I found search_subgraphs returned 0 hits for any multi-word topic: toFulltext AND-joined the prefix terms ("uniswap:* & v3:*"), and The Graph network subgraph's subgraphMetadataSearch fulltext index returns nothing for an AND of multiple prefix terms — so the README's own "uniswap v3 arbitrum" example came back empty. Fixed on this branch by OR-joining ("uniswap:* | v3:*"), verified live against the network subgraph: & → 0 hits, | → 5 hits (Uniswap V4 Arbitrum et al., ranked by signal). The same fix landed upstream in PayQL and shipped to npm payql@0.1.2. The toFulltext unit test is updated to match.

With that in, all three actions check out against the live gateway:

• search_subgraphs — returns ranked hits for multi-word topics (uniswap v3 → 5 subgraphs, top by curation signal).
• get_subgraph_schema — introspection returns the subgraph's entities (verified on Uniswap v3: factory, pool, token, tick, position, …).
• query_subgraph (paid) — I confirmed a real x402 v2 payment settles against The Graph's x402 gateway: $0.01 USDC on Base (EIP-3009), and the query returns data. The gateway advertises Payment-Signature/v2, which the @x402/fetch stack this provider uses speaks — so the paid path works against the live endpoint, not just in mocks.

CI should re-run on the two new commits. Happy to add an example-chatbot transcript if useful. Thanks for taking a look!