@stacknet/x402payg

Pay-as-you-go client SDK. A PAYG key is a pg_ API key bound to your wallet by your wallet's signature and funded by an on-chain payment. StackNet routes reserve each call's price against that funding before running it and return HTTP 402 when it can't cover the call; the client raises that as a typed PaymentRequired with required / remaining, and topUpFor tops the key up so you can retry. Buy, use, top up, list and revoke keys.

npm install @stacknet/x402payg

import { Keypair } from '@solana/web3.js';
import { X402PaygClient, walletFromKeypair } from '@stacknet/x402payg';

const payg = new X402PaygClient({ stacknetBaseUrl: 'https://stacknet.magma-rpc.com' });
const wallet = walletFromKeypair(Keypair.fromSecretKey(secretKey));

const { apiKey, quote } = await payg.createKey(wallet, {
  stackId: 'stk_jmqog66ha0mugmro',
  mint: 'SOL',
  amount: 10_000_000n,
});

• Purchase quotes. Before paying, the client requests a short-lived server quote bound to the wallet, stack, mint and amount, and commits its id on chain as the metadata nonce. The key is credited the quoted amount. purchaseQuotes: 'auto' | 'required' | 'off'.
• Signed preflight. With a wallet signer the config preflight carries a signed challenge (x402-payg-v1:config:<wallet>:<ts>), so wallet-specific invite and spend data is returned only to that wallet.
• Signing domains. Since 0.5.0 every wallet signature uses the x402-payg-v1: domains (key, list, revoke, allow-invite, reserve, config); app-invite reservations sign stacknet-payg-v2:reserve-app:. StackNet 3.16.164 and later also accept the original stacknet-payg-v1: form, so keys from earlier SDKs keep working and a key re-derived with 0.5.0 reaches the same balance. Use 0.5.0 only against StackNet 3.16.164 or later.
• Protocol limits. X402PAYG_LIMITS is StackNet's x402payg-limits.v1 contract: proof size tiers 286 / 1,111 / 2,222 bytes with 128 bytes of headroom (the SDK picks the smallest tier the metadata fits), proof expiry at most 518,400 s (6 days), signatures fresh for 300 s, quotes valid 600 s, minimum funding 1 cent, 1 token = 1 µUSD, stack ids and nonces at most 128 bytes. The preflight compares the server's published limits with this contract and refuses to pay on a difference (protocol_mismatch).
• 402 Payment Required. callWithKey(apiKey, path, init) throws PaymentRequired (code: 'payment_required', required, remaining, keyId, and shortfall = required − remaining) when a route answers 402 PAYG_TOP_UP_REQUIRED; nothing ran. topUpFor(wallet, params, key, error) tops the key up (or switches/buys) and returns the key to retry with; paymentRequiredFrom(response) parses a 402 you fetched yourself.
• Pay from Ethereum or Robinhood Chain (@stacknet/x402payg/evm, StackNet 3.16.173 or later). new X402PaygEvmClient({ stacknetBaseUrl }).createKeyFromEvm(wallet, { network: 'eip155:1', amount: 18_000_000n, stackId }) pays USDC (Ethereum) or USDG (Robinhood Chain) from an EIP-1193 wallet through a bridge order that delivers exactly amount USDC to the StackNet vault on Solana, credited 1:1 (minimum $18; the payer also pays the bridge's input spread and a fixed 0.001 ETH fee). The SDK decodes the bridge's order before the wallet signs (exact amount, vault receiver and authority, payer as source authority, no external call or affiliate fee) and refuses anything else; each step is checkpointed and resume(wallet, operationId) continues without paying twice.
• Errors. Failures are X402PaygClientError with a stable code; messages never include response bodies, credentials or URLs.

Keep API keys, wallet secrets and invite credentials private. Mainnet only; payments are real.

Full guide: the "PAYG integration guide" page of the Geoff docs.

Releasing

This directory is the only publish source. The x402payg release workflow builds and publishes from a tagged commit on main (x402payg-v<version>) after approval of the protected npm-publish environment. dist/ is committed because apps/geoff imports the package through the workspace; CI fails unless it is exactly build:publish of this source. prepublishOnly re-runs the tests, typecheck and publish build and verifies the packed files contain no source or source maps.