Add x402 Support for Providers

[humanizersequel]

Each provider should support an x402 access regime via the/provider:hypergrid:ware.hypr/x402 endpoint (if WIT issues make that unworkable, /xfour or /xfoz are acceptable substitutes as paths.

This will need to be a wildcard path, ingesting a GET with query parameters in the format /providername?param=value, and it also needs to initially return a 402 response. As a reference, here's what the first response on an initial try to access an x402-gated endpoint:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "resource": "/providername{unclear to me if we need the params in here as well, I don't think that's the case}",
      "description": "Payment for providername",
      "mimeType": "application/json",
      "payTo": "{identical to ~wallet note data}",
      "maxTimeoutSeconds": 300,
      "asset": "{USDC on Base contract}",
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    }
  ]
}

Allowing Hyperapps to support wildcard paths and 402 responses may require some work on the framework itself.

After that response, a well-functioning x402 client will construct an EIP-3009 payment and then retry the request, except this time with some additional payload:

GET /providername?param=value HTTP/1.1
Host: your-node.example
Accept: application/json

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "signature": "0x<eip-712-signature-over-transferWithAuthorization>",
    "authorization": {
      "from": "{sender address}",
      "to":   "{~wallet address}",
      "value": "10000",
      "validAfter":  "1760412207",
      "validBefore": "1760412567",
      "nonce": "0x<32-byte-random>"
    }
  }
}

(the JSON there should be base64 encoded and passed in a X-PAYMENTS header – there's also a fallback where it's sent as a JSON body)

Having received this, the Provider client then calls some known x402 facilitator's /verify endpoint with { paymentPayload, paymentRequirements }. If it receives an {"isValid": true, ...} response, then it knows it is good to fulfill the request. It can call the faciltators /settle endpoint either before or after, but I think it's nice if it does so after it confirms that it was successfully able to call the upstream provider (so the flow is verify -> make and pass through upstream call -> settle).

The end user story we're targeting is "drop in a curl, start selling to x402 clients" — it is precisely the same as the original Hypergrid pitch, except more agnostic to the Operator side of the market.

Useful docs:

https://x402.gitbook.io/x402
https://docs.cdp.coinbase.com/x402/welcome

[humanizersequel]

There actually might not be any blockers at all. We have a general purpose solution for error codes apparently:

https://github.com/hyperware-ai/process_lib/blob/e8b065179ce5d15893a23142416e59c87e0f31f6/src/hyperapp.rs#L100

as well as the ability to ingest query params (I did not know about this):

https://github.com/hyperware-ai/process_lib/blob/6a4b7981bfab49a6b141c35217848a93e67aeeb7/src/hyperapp.rs#L128

Do we actually need wildcard paths where the providername is a part of the path? We could just have it be a GET where the provider name is itself a query param, and this will presumably work as is. Going to test rn.