x402 Pay-As-You-Go

How it works

Think of an arcade: put a coin in, play. With x402 Pay-As-You-Go (PAYG) your Solana wallet is the coin.

Put a little SOL into StackNet’s vault.
Get back an API key that’s already loaded with credit.
Every API call spends a bit of it. Top up when it runs low.

No email, no password, no billing page. The key is created on your machine and never sent to a server.

The name comes from HTTP status 402 Payment Required. x402 is the standard that makes “pay for this request” actually work.

Get a key

npm install @stacknet/x402payg

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

const client = new X402PaygClient({ stacknetBaseUrl: "https://stacknet.magma-rpc.com" });
const wallet = walletFromKeypair(Keypair.fromSecretKey(/* your secret key */));

const { apiKey } = await client.createKeyFromSol(wallet, {
  stackId: "geoff",
  inputLamports: 10_000_000n, // 0.01 SOL
});

Call createKeyFromSol again with the same wallet to top up the existing key.

Use the key

It works exactly like a normal API key, just with a pg_ prefix:

curl --request POST \
  --url https://geoff.ai/api/v1/chat/completions \
  --header 'Authorization: Bearer pg_...' \
  --header 'X-Stack-Id: stk_jmqog66ha0mugmro' \
  --header 'Content-Type: application/json' \
  --data '{"model": "magma", "messages": [{"role": "user", "content": "Hello"}]}'

PAYG is mainnet-only and payments are real. Keep the key and your wallet secret out of client-side code and public repos.

Building an app on Geoff?

By default any wallet can create a key. If you want your users’ wallets to spend only inside your app, under limits you set, use app invites. Your backend holds a secret app invite key. It hands each wallet a short-lived allow invite, which the wallet redeems (by signing a message) to become enrolled in your app. From then on, that wallet’s keys and balances are scoped to your app: spend-capped, tool-restricted, and isolated from any other app the same wallet uses.

// Backend (server-only): never ship appInviteKey to a browser
const payg = new X402PaygClient({
  stacknetBaseUrl: "https://stacknet.magma-rpc.com",
  appInviteKey: process.env.STACKNET_APP_INVITE_KEY,
});

// Browser: fetch a fresh allow invite from your backend
const payg = new X402PaygClient({
  stacknetBaseUrl: "https://stacknet.magma-rpc.com",
  allowInviteProvider: ({ wallet, stackId }) =>
    fetch("/api/payg/invite", { method: "POST", body: JSON.stringify({ wallet, stackId }) })
      .then((r) => r.text()),
});

const enrollment = await payg.ensureAppEnrollment(wallet, "geoff"); // { inviteId, stackId }

Treat wallet + stackId + inviteId as the identity for key lookup and top-ups.
Top up the wallet’s existing key (topUpKeyFromSol) instead of minting new ones.
The app invite key, allow invites, and pg_ keys are all secrets. Don’t log or persist them.

Requires @stacknet/x402payg 0.3.5 or newer.

​How it works

​Get a key

​Use the key

​Building an app on Geoff?

How it works

Get a key

Use the key

Building an app on Geoff?