x402 Payments

POST /v1/wallets/me/pay-and-call lets an agent or application runtime call an x402-protected resource without holding a private key.

The Wallet API currently supports:

• EVM wallets
• x402 version 2
• The exact EVM payment scheme
• Public HTTPS resources

Solana and general-purpose transaction signing are not supported in the first release.

Payment flow

For each request, Naven:

1. Resolves the naven_wallet_ credential to one Privy wallet.
2. Calls the target resource without a payment header.
3. Reads the 402 Payment Required response.
4. Verifies that network, asset, amount, scheme, and resource URL match the caller's constraints.
5. Uses the Privy wallet to sign the EVM x402 authorization.
6. Retries the original request with the x402 payment header.
7. Returns the upstream response and settlement metadata.

If the target is free and does not return 402, Naven returns its response with payment: null.

Fund the wallet

The wallet must already hold the token requested by the x402 resource on the correct EVM network. Wallet funding and balance lookup are not yet provided by the Wallet API.

Use GET /v1/wallets/me to retrieve the wallet address, then fund that address through your existing treasury or on-chain flow.

Set an explicit payment boundary

Every request must include maxPayment:

{
  "network": "eip155:8453",
  "asset": "0xTokenContract",
  "amount": "10000"
}

• network is the exact CAIP-2 EVM network.
• asset is the exact ERC-20 token address.
• amount is the maximum atomic token amount.

Naven pays only an exact requirement that matches the network and asset and whose amount is greater than zero and less than or equal to the limit.

This is a per-request boundary. A runtime can make repeated requests, so it is not a daily or lifetime spending policy. Use a dedicated wallet credential, revoke it when the runtime is retired, and avoid overfunding early-access wallets.

Forward an upstream request

curl https://api.naven.network/v1/wallets/me/pay-and-call \
  --request POST \
  --header "Authorization: Bearer $NAVEN_WALLET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://seller.example.com/market-data",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "symbol": "ETH"
    },
    "maxPayment": {
      "network": "eip155:8453",
      "asset": "0xTokenContract",
      "amount": "10000"
    }
  }'

The outer Authorization header authenticates the Wallet API. Headers for the upstream resource belong inside the JSON headers object.

Safety limits

The first release applies the following protections:

• HTTPS is required.
• Localhost, private IPs, and private DNS results are rejected.
• Redirects are not followed.
• Caller-provided x402 payment headers are rejected.
• Request and response bodies default to a 1 MiB limit.
• Each upstream attempt defaults to a 30-second timeout.
• Response Set-Cookie headers are not returned.
• Every attempted payment is recorded without storing the forwarded request body or headers.

Payment status

The upstream HTTP status is returned separately and does not determine whether the payment settled. A paid resource can settle successfully and still return an application-level 4xx or 5xx response.