x402 Provider Support #98

humanizersequel · 2025-10-17T15:46:38Z

This Provider upgrade allows any provider to be queried via HTTP and for micropayments to settle via the x402 protocol.

It binds the /xfour endpoint which accepts a GET with query parameters like /xfour?providername=name&param1=value&param2=value. These calls are then verified and settled with the facilitator.x402.rs endpoints (/verify and /settle) before the parameters are passed to make the upstream call as usual.

notes:
I have NOT yet tested this with Mainnet Base / USDC, only Sepolia. It should be fine, but EIP-3009 has been finicky so worth testing.

I have also not tested it on a provider that takes more than one parameter.

Also, this relies on features in branches of process lib and the macro that have not been merged yet, and are not necessarily going to be merged in the way that this PR implies.

not real yet, just a checkpoint commit because I'm going to have Claude get real jiggy with it

Checkpoint commit, some jank when calling out to the facilitator that I can't figure out easily

checkpoint commit. lfg

it works (on testnet at least)

Ok seems good, but need to test this with Mainnet Base / USDC (should be fine but there's some fiddly stuff with EIP-3009). Also need to ensure that a migration will be fine.

humanizersequel · 2025-10-17T16:26:27Z

Probably good to support the additional output schema requested here: https://www.x402scan.com/resources/register

I'll take care of that. @Gohlub it would be good if you added an ~x402 note that just had the full URL (https://nodename.hostingplatform.tld/provider:hypergrid:ware.hypr/xfour?providername=providername&param1=param1samplevalue)

Gohlub · 2025-10-20T03:50:31Z

provider/provider/src/lib.rs

+        info!("x402 endpoint called");
+
+        // ===== CHECK FOR X-PAYMENT HEADER =====
+        let x_payment_header = APP_HELPERS.with(|helpers| {


probably should not use APP_HELPERS, iirc its used by the macro internally so we should have some code in process-lib that enables getting the header, same comment for wherever we use it to fetch the relevant context about the http request

Gohlub · 2025-10-20T03:58:26Z

provider/provider/src/lib.rs

    pub spent_tx_hashes: Vec<String>,
+    // TODO: Replace with persistent storage for production - tracks used payment nonces to prevent replay attacks
+    #[serde(skip)]
+    pub used_nonces: HashSet<String>,


we can put this in our key-value store process

avoiding to modify the state also saves us from writing more state migration logic

though since we need the new note, we might have to do it anyways lol

Kind of annoying that we have to write migration logic for every single note we try to add (or, presumably, remove). Is there some obvious way around this or do we just have to suck it up?

it's just about state persistence: it is plausible we can move provider metadata to not live in the state as it's all public info anyways, though imo changing the structure of notes on a protocol level should only happen on higher version bumps: because of the distributed nature of our deployments, for every such change we have to add extra logic that nudges, and correctly tracks what is missing in the client (provider in our case) to get on their node and sign extra transactions, I had to do such extra work for the is_live note from some time ago

furthermore, we have restrictions on what notes are allowed in the namespace so that's yet another dependency we need to keep a track off

Note: check if #[serde(skip)] means this won't break state and cause a panic.

Generally, we should test the upgrade path, @Gohlub only flagged this as a potential state troll but who knows

to be clear it isn't super important to keep track of the nonces. EIP 3009 kind of does it for us

Got rid of it.

Gohlub · 2025-10-20T04:01:35Z

provider/provider/src/lib.rs

+            };
+
+            // Validate protocol version
+            if payment_payload.protocol_version != 1 {


unless there's a specific reason we're doing the validation here, it makes more sense to do it sooner rather than later: if the client is using an outdated protocol version (not sure if payment would go through in the first place), we don't want them to get rejected after being told to send the payment

inspecting the code further, I see this comes from 'parse_x_payment_header', which is the second step so it actually does make sense to do this here, I am not sure exactly about how x402 is set up but I feel like validating the protocol version should be done sooner

I don't think it's a huge deal because of how EIP-3009 works — a modified malicious client could maybe steal user funds by counterfeiting everything after receiving the signature on false pretenses, but I'm not sure about that and if it is the case it's a problem across all x402 clients not just this implementation.

Gohlub · 2025-10-20T04:17:37Z

provider/provider/src/lib.rs

+                        payment_payload.scheme, payment_payload.network);
+                    method
+                },
+                None => {


defensive validation (which is okay), but unclear why this would be None given the contents of build_payment_requirements as those fields are populated by constants "exact" and "X402_PAYMENT_NETWORK"

Gohlub · 2025-10-20T04:24:24Z

provider/provider/src/lib.rs

+                return Ok("".to_string());
+            }
+
+            info!("Payment verified for payer: {}", verify_result.payer);


info! will be propagated to hypergrid_logger, so we should send this log after replay protection check
also, we should update the hypergrid_logger process to include x402 payments

Gohlub · 2025-10-20T04:40:17Z

haven't ran the code but it looks good (will require small modifications), will probably want to abstract the logic from the handler and put it in util.rs (just for better readability)

Gohlub · 2025-10-20T04:43:55Z

Probably good to support the additional output schema requested here: https://www.x402scan.com/resources/register

I'll take care of that. @Gohlub it would be good if you added an ~x402 note that just had the full URL (https://nodename.hostingplatform.tld/provider:hypergrid:ware.hypr/xfour?providername=providername&param1=param1samplevalue)

I might just be spitballing but I need to check in with Nick since I get the feeling that this might not work for self-hosted indirect nodes.

Gohlub · 2025-10-20T04:52:48Z

provider/provider/src/lib.rs

+/// Build PaymentRequirements structure from provider and resource URL
+fn build_payment_requirements(provider: &RegisteredProvider, resource_url: &str) -> PaymentRequirements {
+    // Convert USDC price to atomic units (6 decimals)
+    let max_amount_atomic = ((provider.price * 1_000_000.0) as u64).to_string();


Yeah I had flagged this previously but just got lazy about it, will fix.

Gohlub · 2025-10-20T17:12:11Z

Probably good to support the additional output schema requested here: https://www.x402scan.com/resources/register
I'll take care of that. @Gohlub it would be good if you added an ~x402 note that just had the full URL (https://nodename.hostingplatform.tld/provider:hypergrid:ware.hypr/xfour?providername=providername&param1=param1samplevalue)

I might just be spitballing but I need to check in with Nick since I get the feeling that this might not work for self-hosted indirect nodes.

just checked in with Nick: the note should be optional as it would otherwise doxx indirect nodes

Gohlub · 2025-10-20T17:13:36Z

Do you mind sharing more info about sepolia/base discrepency RE EIP-3009?

humanizersequel · 2025-10-20T17:18:20Z

RE sepolia/base there's a few: EIP-3009 expects a network name, token addresses, and then crucially the onchain name of the token matters. On Base it is "USD Coin" and on Sepolia it is "USDC" (or maybe the other way around I can't remember) and you need to specify that.

RE doxxing indirect nodes: does that mean that indirect nodes can never field inbound HTTP requests? I'm not understanding what the problem here is. If it's really just "doxxing" (in the sense that you know what URL someone hosts their node at) it's a nonissue since you don't have to use Hypergrid if you're that sensitive about opsec. If there's an actual risk that's different, but I can't imagine how that would be the case.

Gohlub · 2025-10-20T19:44:44Z

RE sepolia/base there's a few: EIP-3009 expects a network name, token addresses, and then crucially the onchain name of the token matters. On Base it is "USD Coin" and on Sepolia it is "USDC" (or maybe the other way around I can't remember) and you need to specify that.

RE doxxing indirect nodes: does that mean that indirect nodes can never field inbound HTTP requests? I'm not understanding what the problem here is. If it's really just "doxxing" (in the sense that you know what URL someone hosts their node at) it's a nonissue since you don't have to use Hypergrid if you're that sensitive about opsec. If there's an actual risk that's different, but I can't imagine how that would be the case.

it's doxxing in the sense of that providers will post their home IP address on-chain, and I think it might even require them to fiddle with their routers to expose ports to the internet (it's why the node boot-sequence defaults to indirect and warns you do leave it like that unless you know what you're doing). Indirect nodes can handle inbound HTTP requests, but in that case if you're willing to share your IP address with the service that is trying to reach your node

humanizersequel · 2025-10-20T20:12:33Z

I strongly feel this is a non-issue because Hypergrid itself is opt-in.

However, given the absolute state of Hypergrid GTM right now, I don't think it even matters if we try to rush an ~x402 link into prod. We can implement this without it, and lean on 3p x402 registries to start off with.

@Gohlub

@Gohlub insisting I abstract my shit. smdh.

not necessary, EIP-3009 doesn't give much surface area for this kind of thing anyway

you know what it is

should still work with orthodox x402 clients (whatever that means) and also now x402scans more involved schema will let them generate a UI to make calls in-app

humanizersequel · 2025-10-21T16:34:00Z

Ok, this is the last featureful commit. x402 + the extended schema for x402scan is done.

To do:

test that it works with mainnet providers (@humanizersequel)
test that the upgrade is smooth from a previous version of hypergrid (@humanizersequel)
make the code readable (move stuff into utils.rs) (@Gohlub)
remove dependence on Set response body process_lib#170 + Update lib.rs hyperapp-macro#50 (someone)

humanizersequel · 2025-10-23T03:10:29Z

upgrade path is fine. the whole state management thing in the app framework is a huge pain though, wish it would handle it more gracefully

humanizersequel · 2025-10-23T12:35:25Z

and the sh build.sh --env production path works just fine

@Gohlub I want to get this out today. If you've like to break some of the business logic out into a separate file now's the time

humanizersequel · 2025-10-23T16:09:47Z

Let's make it so that provider:hypergrid:ware.hypr takes priority in the UI (when you click the Hypergrid button, it should open straight to that interface).

moved logic to util.rs

humanizersequel · 2025-10-23T17:49:40Z

"I approve"

humanizersequel added 5 commits October 15, 2025 18:18

x402

641273f

not real yet, just a checkpoint commit because I'm going to have Claude get real jiggy with it

Update lib.rs

7c6b404

Checkpoint commit, some jank when calling out to the facilitator that I can't figure out easily

ok it kind of works now

1b74ec2

checkpoint commit. lfg

this the one

4a09bc1

it works (on testnet at least)

Ready for merge, in principle

0ef629c

Ok seems good, but need to test this with Mainnet Base / USDC (should be fine but there's some fiddly stuff with EIP-3009). Also need to ensure that a migration will be fine.

humanizersequel requested a review from Gohlub October 17, 2025 15:46

humanizersequel changed the title ~~x402 Support~~ x402 Provider Support Oct 17, 2025

Gohlub reviewed Oct 20, 2025

View reviewed changes

humanizersequel added 4 commits October 21, 2025 11:12

abstracts APP_HELPERS functions

3021802

@Gohlub insisting I abstract my shit. smdh.

eliminates replay checks

ff9f74f

not necessary, EIP-3009 doesn't give much surface area for this kind of thing anyway

muh floating point

aabcb65

you know what it is

More advanced schema for x402scan

18ea0fc

should still work with orthodox x402 clients (whatever that means) and also now x402scans more involved schema will let them generate a UI to make calls in-app

moved logic to util.rs

6f1556e

Merge pull request #101 from hyperware-ai/pr-98

af389c9

moved logic to util.rs

humanizersequel merged commit af40cc6 into develop Oct 23, 2025

humanizersequel deleted the x402 branch October 23, 2025 17:49

x402 Provider Support #98

x402 Provider Support #98

Uh oh!

Conversation

humanizersequel commented Oct 17, 2025

Uh oh!

humanizersequel commented Oct 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Gohlub Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Gohlub commented Oct 20, 2025

Uh oh!

Gohlub commented Oct 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Gohlub commented Oct 20, 2025

Uh oh!

Gohlub commented Oct 20, 2025

Uh oh!

humanizersequel commented Oct 20, 2025

Uh oh!

Gohlub commented Oct 20, 2025

Uh oh!

humanizersequel commented Oct 20, 2025

Uh oh!

humanizersequel commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

humanizersequel commented Oct 23, 2025

Uh oh!

humanizersequel commented Oct 23, 2025

Uh oh!

humanizersequel commented Oct 23, 2025

Uh oh!

humanizersequel commented Oct 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Gohlub Oct 20, 2025 •

edited

Loading

humanizersequel commented Oct 21, 2025 •

edited

Loading