x402 Pay-As-You-Go

## Task
 
Add StackNet pay-as-you-go top-ups to this Next.js app using `@stacknet/x402payg`. Users pay from their Solana wallet (Phantom/Solflare via wallet-adapter), receive a `pg_` API key with a prepaid token budget, and the app uses that key as the Bearer token for StackNet inference calls. No signup or account system — the wallet signature is the only credential.
 
## Stack details
 
- Stack ID: `STACK_ID`
- StackNet URL: `https://stacknet.magma-rpc.com`
- Network: Solana MAINNET
 
## Steps
 
### 1. Install
 
```bash
npm install @stacknet/x402payg @solana/wallet-adapter-react @solana/wallet-adapter-wallets @solana/web3.js
```
 
### 2. Environment variables
 
Add to `.env.local`:
 
```
NEXT_PUBLIC_STACK_ID=STACK_ID
NEXT_PUBLIC_STACKNET_XPC_URL=https://stacknet.magma-rpc.com
```
 
### 3. Create the PAYG hook
 
Create `hooks/use-payg.ts`:
 
```ts
'use client'
 
import { useMemo, useState, useCallback } from 'react'
import { useWallet } from '@solana/wallet-adapter-react'
import { X402PaygClient, type PaygKeyInfo } from '@stacknet/x402payg'
 
const client = new X402PaygClient({
  stacknetBaseUrl: process.env.NEXT_PUBLIC_STACKNET_XPC_URL || 'https://stacknet.magma-rpc.com',
})
 
export function usePayg() {
  const wallet = useWallet()
  const [keys, setKeys] = useState<PaygKeyInfo[]>([])
  const [busy, setBusy] = useState(false)
 
  // wallet-adapter wallets are structurally compatible with PaygWallet
  const paygWallet = useMemo(() => {
    if (!wallet.publicKey || !wallet.signMessage) return null
    return {
      publicKey: wallet.publicKey,
      signMessage: wallet.signMessage,
      sendTransaction: wallet.sendTransaction,
    }
  }, [wallet.publicKey, wallet.signMessage, wallet.sendTransaction])
 
  const topUp = useCallback(async (usdcAmount: number) => {
    if (!paygWallet) throw new Error('connect a wallet first')
    setBusy(true)
    try {
      const created = await client.createKey(paygWallet, {
        amount: BigInt(Math.round(usdcAmount * 1_000_000)), // USDC 6dp
        mint: 'USDC',
        stackId: process.env.NEXT_PUBLIC_STACK_ID || '',
      })
      return created // { apiKey, proofPda, txSignature, ... }
    } finally {
      setBusy(false)
    }
  }, [paygWallet])
 
  const refreshKeys = useCallback(async () => {
    if (!paygWallet) return
    setKeys(await client.getActiveKeys(paygWallet))
  }, [paygWallet])
 
  const recoverKey = useCallback(async (proofPda: string) => {
    if (!paygWallet) throw new Error('connect a wallet first')
    return client.deriveApiKeyFor(paygWallet, proofPda)
  }, [paygWallet])
 
  const revoke = useCallback(async (keyId: string) => {
    if (!paygWallet) throw new Error('connect a wallet first')
    await client.revokeKey(paygWallet, keyId)
    await refreshKeys()
  }, [paygWallet, refreshKeys])
 
  return { topUp, refreshKeys, recoverKey, revoke, keys, busy, connected: !!paygWallet }
}
```
 
### 4. Build the top-up UI
 
Create a top-up panel with preset amounts ($1 / $5 / $25), a "Top up" button that calls `topUp()`, and a key list showing `tokensRemaining` / `tokenBudget` per key with a progress bar and a revoke button. After a successful top-up, store ONLY the `proofPda` (e.g. localStorage) — NEVER persist the raw `pg_` key; re-derive it with `recoverKey(proofPda)` when needed.
 
### 5. Use the key for inference
 
```ts
const apiKey = await recoverKey(proofPda)
const res = await fetch(`${process.env.NEXT_PUBLIC_STACKNET_XPC_URL}/v1/chat/completions`, {
  method: 'POST',
  headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
  body: JSON.stringify({ model: 'magma', messages }),
})
```
 
When a call fails with a "depleted" error, surface the top-up panel again.
 
## Result
 
After completing these steps you will have:
- Wallet-signed pay-as-you-go top-ups (USDC or PAPER on mainnet) with no account system
- `pg_` API keys derived from wallet signatures — never persisted anywhere
- A key dashboard with live budget bars, recovery, and revoke
- StackNet inference calls billed against the prepaid budget

## Task
 
Write a Node.js script/CLI for StackNet pay-as-you-go using `@stacknet/x402payg`: mint a `pg_` API key from a funded Solana keypair, spend it against StackNet chat completions, report the remaining budget, and support revoke. This is for server-side / headless use — no browser, no wallet extension.
 
## Stack details
 
- Stack ID: `STACK_ID`
- StackNet URL: `https://stacknet.magma-rpc.com`
- Network: Solana MAINNET
- Wallet: bs58-encoded secret key in the `WALLET_SECRET` env var (never hardcode it, never log it)
 
## Steps
 
### 1. Install
 
```bash
npm install @stacknet/x402payg @solana/web3.js bs58
```
 
### 2. Create the CLI
 
Create `payg.ts` with four subcommands:
 
**`topup <usd>`** — mint a key for `<usd>` dollars of SOL:
 
```ts
import { Keypair, LAMPORTS_PER_SOL } from '@solana/web3.js'
import bs58 from 'bs58'
import { X402PaygClient, walletFromKeypair } from '@stacknet/x402payg'
 
const wallet = walletFromKeypair(Keypair.fromSecretKey(bs58.decode(process.env.WALLET_SECRET!)))
const client = new X402PaygClient({ stacknetBaseUrl: 'https://stacknet.magma-rpc.com' })
 
// fetch SOL/USD (e.g. CoinGecko), convert usd → lamports, then:
const created = await client.createKey(wallet, {
  amount: BigInt(Math.ceil((usd / solPriceUsd) * LAMPORTS_PER_SOL)),
  mint: 'SOL',
  stackId: 'STACK_ID',
})
console.log('key:', created.apiKey)
console.log('proof:', created.proofPda)
```
 
Print the key ONCE to stdout and store only the proofPda in a local state file (`~/.payg.json`). The key is re-derivable — never write it to disk.
 
**`status`** — list keys with budget:
 
```ts
const keys = await client.listKeys(wallet)
for (const k of keys) {
  console.log(`${k.keyId}  ${k.status}  ${k.tokensRemaining.toLocaleString()}/${k.tokenBudget.toLocaleString()} tokens  (${k.mint})`)
}
```
 
**`chat <prompt>`** — spend against the best available key:
 
```ts
const best = await client.pickKey(wallet)
if (!best) throw new Error('no spendable keys — run: payg topup 5')
const apiKey = await client.deriveApiKeyFor(wallet, best.proofPda)
 
const res = await fetch('https://stacknet.magma-rpc.com/v1/chat/completions', {
  method: 'POST',
  headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
  body: JSON.stringify({ model: 'magma', messages: [{ role: 'user', content: prompt }] }),
})
console.log((await res.json()).choices?.[0]?.message?.content)
```
 
**`revoke <keyId>`** — kill a leaked key:
 
```ts
await client.revokeKey(wallet, keyId)
```
 
### 3. Error handling
 
- `createKey` register is retry-safe: on a network error after the tx confirmed, retry — re-registering the same proof is idempotent, and the budget only credits after finalization (~30s).
- A 401/402 with "depleted" on chat → print the top-up hint and exit non-zero.
- Never print `WALLET_SECRET` or the derived key except the single explicit `topup` output.
 
## Result
 
A `payg` CLI with `topup` / `status` / `chat` / `revoke`, storing only proof addresses on disk, spending SOL from a headless keypair, with deterministic key recovery.

## Task
 
Give this AI agent the ability to fund its own StackNet inference using `@stacknet/x402payg`. The agent holds a Solana keypair with a small SOL allowance. When its prepaid budget runs low, it autonomously tops up (within a hard spending cap), then continues making inference calls with the freshly minted `pg_` key. This is the x402 pattern: machine-payable APIs, no human in the loop per purchase.
 
## Stack details
 
- Stack ID: `STACK_ID`
- StackNet URL: `https://stacknet.magma-rpc.com`
- Network: Solana MAINNET
- Agent wallet: bs58 secret in `AGENT_WALLET_SECRET`
- HARD caps (enforce in code, not prompts): `MAX_TOPUP_USD_PER_DAY`, `MAX_SINGLE_TOPUP_USD`
 
## Steps
 
### 1. Install
 
```bash
npm install @stacknet/x402payg @solana/web3.js bs58
```
 
### 2. Create the self-funding budget manager
 
Create `agent-budget.ts`:
 
```ts
import { Keypair } from '@solana/web3.js'
import bs58 from 'bs58'
import { X402PaygClient, walletFromKeypair, type PaygKeyInfo } from '@stacknet/x402payg'
 
const LOW_WATER_TOKENS = 200_000        // re-fund below this (~$0.20 left)
const TOPUP_USDC = 5                    // $5 per top-up
 
const wallet = walletFromKeypair(Keypair.fromSecretKey(bs58.decode(process.env.AGENT_WALLET_SECRET!)))
const client = new X402PaygClient({ stacknetBaseUrl: 'https://stacknet.magma-rpc.com' })
 
export async function getSpendableKey(): Promise<string> {
  let best = await client.pickKey(wallet)
 
  const remaining = best?.tokensRemaining ?? 0
  if (remaining < LOW_WATER_TOKENS) {
    assertUnderDailyCap(TOPUP_USDC)      // throw if the cap would be exceeded
    const created = await client.createKey(wallet, {
      amount: BigInt(TOPUP_USDC * 1_000_000), // USDC 6dp
      mint: 'USDC',
      stackId: 'STACK_ID',
    })
    recordSpend(TOPUP_USDC)              // persist for the daily-cap ledger
    return created.apiKey
  }
 
  return client.deriveApiKeyFor(wallet, best!.proofPda)
}
```
 
Implement `assertUnderDailyCap`/`recordSpend` against a small local ledger file — the cap check MUST be code, never an LLM decision.
 
### 3. Wire into the agent's inference client
 
Wrap the agent's LLM call so a depleted-key failure triggers exactly one refund-and-retry:
 
```ts
async function agentInference(messages: unknown[]) {
  for (let attempt = 0; attempt < 2; attempt++) {
    const apiKey = await getSpendableKey()
    const res = await fetch('https://stacknet.magma-rpc.com/v1/chat/completions', {
      method: 'POST',
      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
      body: JSON.stringify({ model: 'magma', messages }),
    })
    if (res.ok) return res.json()
    const body = await res.text()
    if (!/depleted/i.test(body) || attempt === 1) throw new Error(`inference failed: ${res.status} ${body}`)
    // depleted mid-flight → loop once; getSpendableKey will top up
  }
}
```
 
### 4. Safety rails (non-negotiable)
 
- Spending caps enforced in code with a persisted ledger; refuse to top up when exceeded and surface a clear error for the operator.
- The wallet holds ONLY the operating allowance — treat it as hot and disposable.
- Log every top-up: timestamp, txSignature, proofPda, USD amount. Never log the secret or the derived key.
- On operator command, revoke all active keys: `for (const k of await client.getActiveKeys(wallet)) await client.revokeKey(wallet, k.keyId)`.
 
## Result
 
An agent that pays for its own inference: monitors its prepaid budget, tops up autonomously under hard code-enforced caps, recovers keys deterministically from its wallet, and can be instantly de-funded by revoking keys.