openclaw-algorand-plugin 0.5.0

package/skills/algorand-x402-typescript/references/create-typescript-x402-client-reference.md

@@ -0,0 +1,371 @@
+# x402 HTTP Client Reference
+
+Detailed API reference for `@x402-avm/fetch`, `@x402-avm/axios`, and `@x402-avm/avm` client packages.
+
+## Package: @x402-avm/fetch
+
+### Installation
+
+```bash
+npm install @x402-avm/fetch @x402-avm/avm algosdk
+```
+
+### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `wrapFetchWithPayment` | Function | Wraps fetch with automatic 402 payment handling |
+| `wrapFetchWithPaymentFromConfig` | Function | Config-based variant of the above |
+| `x402Client` | Class | Core client for managing payment schemes |
+| `x402HTTPClient` | Class | HTTP-level payment client |
+| `decodePaymentResponseHeader` | Function | Decodes the PAYMENT-RESPONSE header |
+| `PaymentPolicy` | Type | Policy function type for filtering requirements |
+| `SchemeRegistration` | Type | Scheme registration configuration |
+| `x402ClientConfig` | Type | Configuration object type |
+| `PaymentRequired` | Type | 402 response structure |
+| `PaymentRequirements` | Type | Individual payment requirement |
+| `PaymentPayload` | Type | Signed payment payload |
+| `Network` | Type | Network identifier string type |
+| `SchemeNetworkClient` | Type | Client-side scheme interface |
+
+### wrapFetchWithPayment
+
+Wraps a standard `fetch` function with automatic 402 payment handling.
+
+```typescript
+function wrapFetchWithPayment(
+  fetch: typeof globalThis.fetch,
+  client: x402Client | x402HTTPClient,
+): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+```
+
+**Flow:**
+1. Makes the initial HTTP request normally
+2. If the server responds with 402, parses payment requirements from the response
+3. Selects a suitable payment method based on registered schemes
+4. Creates a payment payload by signing a transaction group
+5. Retries the request with the `PAYMENT-SIGNATURE` header
+6. If the response is anything other than 402, returns it as-is
+
+### wrapFetchWithPaymentFromConfig
+
+Config-based variant that creates the `x402Client` internally.
+
+```typescript
+function wrapFetchWithPaymentFromConfig(
+  fetch: typeof globalThis.fetch,
+  config: x402ClientConfig,
+): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+```
+
+### x402ClientConfig
+
+```typescript
+interface x402ClientConfig {
+  schemes: Array<{
+    network: string;       // CAIP-2 identifier or wildcard ("algorand:*")
+    client: SchemeNetworkClient;
+  }>;
+  policies?: PaymentPolicy[];
+}
+```
+
+### PaymentPolicy
+
+```typescript
+type PaymentPolicy = (
+  version: number,
+  requirements: PaymentRequirements[],
+) => PaymentRequirements[];
+```
+
+Policies are applied in registration order. Each policy receives the remaining requirements and returns a filtered/transformed list.
+
+### decodePaymentResponseHeader
+
+```typescript
+function decodePaymentResponseHeader(header: string): any;
+```
+
+Decodes the `PAYMENT-RESPONSE` header returned by the server after settlement.
+
+---
+
+## Package: @x402-avm/axios
+
+### Installation
+
+```bash
+npm install @x402-avm/axios @x402-avm/avm algosdk axios
+```
+
+### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `wrapAxiosWithPayment` | Function | Wraps Axios instance with 402 payment interceptor |
+| `wrapAxiosWithPaymentFromConfig` | Function | Config-based variant of the above |
+| `x402Client` | Class | Core client for managing payment schemes |
+| `x402HTTPClient` | Class | HTTP-level payment client |
+| `decodePaymentResponseHeader` | Function | Decodes the PAYMENT-RESPONSE header |
+| `PaymentPolicy` | Type | Policy function type for filtering requirements |
+| `SchemeRegistration` | Type | Scheme registration configuration |
+| `x402ClientConfig` | Type | Configuration object type |
+| `PaymentRequired` | Type | 402 response structure |
+| `PaymentRequirements` | Type | Individual payment requirement |
+| `PaymentPayload` | Type | Signed payment payload |
+| `Network` | Type | Network identifier string type |
+| `SchemeNetworkClient` | Type | Client-side scheme interface |
+
+### wrapAxiosWithPayment
+
+Adds a response interceptor that handles 402 responses by signing and submitting payment transactions.
+
+```typescript
+function wrapAxiosWithPayment(
+  axiosInstance: AxiosInstance,
+  client: x402Client | x402HTTPClient,
+): AxiosInstance;
+```
+
+Returns the same Axios instance (mutated with the interceptor). The interceptor:
+- Catches 402 responses
+- Parses payment requirements (headers for V2, body for V1)
+- Creates payment payload via `x402Client`
+- Marks the request with `__is402Retry = true` to prevent infinite loops
+- Retries with `PAYMENT-SIGNATURE` header
+
+### wrapAxiosWithPaymentFromConfig
+
+```typescript
+function wrapAxiosWithPaymentFromConfig(
+  axiosInstance: AxiosInstance,
+  config: x402ClientConfig,
+): AxiosInstance;
+```
+
+### Interceptor Behavior
+
+```
+Client Request --> Axios sends request --> Server Response
+                                              |
+                       Status != 402 -------> Return response normally
+                       Status == 402 -------> Already retried? --> Reject
+                                              |
+                                              Parse PaymentRequired
+                                              Create payment payload
+                                              Retry with PAYMENT-SIGNATURE
+                                              Return retried response
+```
+
+Key details:
+- **Single retry**: Only retries once per 402
+- **Request mutation**: Modifies original config and retries via `axiosInstance.request()`
+- **Concurrent requests**: Each 402 is handled independently
+- **Interceptor order**: Payment interceptor should be added last
+
+---
+
+## Package: @x402-avm/avm
+
+### Installation
+
+```bash
+npm install @x402-avm/avm algosdk
+```
+
+### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ExactAvmScheme` | Class | Algorand exact payment scheme (client) |
+| `ClientAvmSigner` | Interface | Signer interface for client wallets |
+| `ClientAvmConfig` | Interface | Algod client configuration |
+| `ALGORAND_TESTNET_CAIP2` | Constant | `"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` |
+| `ALGORAND_MAINNET_CAIP2` | Constant | `"algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="` |
+| `isAvmSignerWallet` | Function | Type guard for ClientAvmSigner |
+
+### ClientAvmSigner Interface
+
+The interface that bridges wallets (browser or server) to the x402 payment system.
+
+```typescript
+interface ClientAvmSigner {
+  /** The Algorand address of the payer */
+  address: string;
+
+  /**
+   * Sign one or more transactions in a group.
+   * @param txns - Array of unsigned transaction bytes (msgpack)
+   * @param indexesToSign - Optional indices of transactions to sign.
+   *                        If omitted, sign all transactions.
+   * @returns Array where signed transactions contain the signed blob,
+   *          and skipped transactions are null
+   */
+  signTransactions(
+    txns: Uint8Array[],
+    indexesToSign?: number[],
+  ): Promise<(Uint8Array | null)[]>;
+}
+```
+
+### Subpath: @x402-avm/avm/exact/client
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `registerExactAvmScheme` | Function | Registers AVM schemes (V1 + V2) to an x402Client |
+| `AvmClientConfig` | Interface | Configuration for AVM client registration |
+
+### registerExactAvmScheme
+
+```typescript
+function registerExactAvmScheme(
+  client: x402Client,
+  config: AvmClientConfig,
+): void;
+```
+
+### AvmClientConfig
+
+```typescript
+interface AvmClientConfig {
+  /** The client signer implementation */
+  signer: ClientAvmSigner;
+
+  /** Optional Algod configuration */
+  algodConfig?: {
+    /** Algod URL (defaults to AlgoNode testnet/mainnet) */
+    algodUrl?: string;
+    /** Algod API token */
+    algodToken?: string;
+    /** Pre-configured Algodv2 client */
+    algodClient?: algosdk.Algodv2;
+  };
+
+  /** Optional: restrict to specific networks */
+  networks?: string[];
+}
+```
+
+---
+
+## x402Client Class
+
+### Constructor
+
+```typescript
+const client = new x402Client(selector?: PaymentRequirementsSelector);
+```
+
+Optional `selector` overrides default selection logic for choosing among payment requirements.
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `registerPolicy` | `(policy: PaymentPolicy) => x402Client` | Register a payment policy (chainable) |
+| `onBeforePaymentCreation` | `(hook: BeforePaymentHook) => void` | Register pre-payment hook |
+| `onAfterPaymentCreation` | `(hook: AfterPaymentHook) => void` | Register post-payment hook |
+| `onPaymentCreationFailure` | `(hook: PaymentFailureHook) => void` | Register failure hook |
+
+### Lifecycle Hooks
+
+**BeforePaymentCreation:**
+```typescript
+client.onBeforePaymentCreation(async (context) => {
+  // context.selectedRequirements - the chosen payment requirements
+  // context.paymentRequired - full 402 response
+  // Return { abort: true, reason: "..." } to cancel payment
+});
+```
+
+**AfterPaymentCreation:**
+```typescript
+client.onAfterPaymentCreation(async (context) => {
+  // context.paymentPayload - the signed payload
+  // context.paymentRequired - full 402 response
+});
+```
+
+**PaymentCreationFailure:**
+```typescript
+client.onPaymentCreationFailure(async (context) => {
+  // context.error - the error that occurred
+  // Return { recovered: true, payload: ... } to provide fallback
+});
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description | Format |
+|----------|-------------|--------|
+| `AVM_PRIVATE_KEY` | Algorand private key | Base64-encoded 64-byte key (32-byte seed + 32-byte pubkey) |
+| `ALGOD_TESTNET_URL` | Custom Algod testnet URL | URL string (default: `https://testnet-api.algonode.cloud`) |
+| `ALGOD_MAINNET_URL` | Custom Algod mainnet URL | URL string (default: `https://mainnet-api.algonode.cloud`) |
+
+---
+
+## Network Constants
+
+| Constant | Value |
+|----------|-------|
+| `ALGORAND_TESTNET_CAIP2` | `"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` |
+| `ALGORAND_MAINNET_CAIP2` | `"algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="` |
+| `V1_ALGORAND_TESTNET` | `"algorand-testnet"` |
+| `V1_ALGORAND_MAINNET` | `"algorand-mainnet"` |
+
+---
+
+## Testing
+
+### Unit Testing a Client
+
+```typescript
+import { x402Client } from "@x402-avm/fetch";
+import { registerExactAvmScheme } from "@x402-avm/avm/exact/client";
+
+// Create a mock signer for testing
+const mockSigner = {
+  address: "TEST_ADDRESS_58_CHARS_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+  signTransactions: async (txns: Uint8Array[], indexesToSign?: number[]) => {
+    return txns.map((_, i) => {
+      if (indexesToSign && !indexesToSign.includes(i)) return null;
+      return new Uint8Array([0x80]); // mock signed bytes
+    });
+  },
+};
+
+const client = new x402Client();
+registerExactAvmScheme(client, { signer: mockSigner });
+```
+
+### Integration Testing with Real Transactions
+
+```bash
+# Set up environment
+export AVM_PRIVATE_KEY="your-base64-key-here"
+
+# Run with tsx
+npx tsx client-test.ts https://api.example.com/paid-endpoint
+```
+
+---
+
+## Important Notes
+
+- `AVM_PRIVATE_KEY` is a Base64-encoded 64-byte key. The first 32 bytes are the seed, the last 32 bytes are the public key.
+- Address derivation always uses `algosdk.encodeAddress(secretKey.slice(32))` -- the public key portion.
+- The `algorand:*` wildcard in config-based setups matches any Algorand network (testnet or mainnet).
+- Policies are composable and applied in order. An empty result from any policy means no payment options are available.
+- The Axios interceptor modifies the instance in place and returns it. Do not create a new instance after wrapping.
+
+---
+
+## External Resources
+
+- [x402-avm Examples Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [x402-avm Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)
+- [@txnlab/use-wallet Documentation](https://txnlab.gitbook.io/use-wallet)
+- [algosdk TypeScript Reference](https://algorand.github.io/js-algorand-sdk/)

package/skills/algorand-x402-typescript/references/create-typescript-x402-client.md

@@ -0,0 +1,236 @@
+# Creating x402 HTTP Clients (Fetch and Axios)
+
+Build HTTP clients that automatically detect `402 Payment Required` responses, sign Algorand transactions, and retry requests with payment proof -- all transparently.
+
+## Prerequisites
+
+Before using this skill, ensure:
+
+1. **Node.js or browser environment** with TypeScript support
+2. **An Algorand wallet or private key** for signing payment transactions
+3. **USDC balance** on the target network (testnet or mainnet) in the payer's account
+
+## Core Workflow: The 402 Payment Flow
+
+The key insight is that `wrapFetchWithPayment` and `wrapAxiosWithPayment` intercept 402 responses, sign a transaction group, and retry the original request with the payment header -- all automatically:
+
+```
+Client Request (GET /api/premium)
+         |
+         v
+   Server Response
+         |
+         +-- Status != 402 --> Return response as-is
+         |
+         +-- Status == 402 -->
+               |
+               +-- Parse PaymentRequired (headers V2 / body V1)
+               +-- Select scheme via registered x402Client
+               +-- Build atomic transaction group
+               +-- Sign with ClientAvmSigner (wallet or private key)
+               +-- Encode PAYMENT-SIGNATURE header
+               +-- Retry original request with payment header
+               |
+               v
+           Return retried response
+```
+
+## How to Proceed
+
+### Step 1: Install Dependencies
+
+For Fetch-based clients:
+```bash
+npm install @x402-avm/fetch @x402-avm/avm algosdk
+```
+
+For Axios-based clients:
+```bash
+npm install @x402-avm/axios @x402-avm/avm algosdk axios
+```
+
+### Step 2: Implement a ClientAvmSigner
+
+The `ClientAvmSigner` interface is what bridges your wallet or private key to the x402 payment system.
+
+**Interface:**
+```typescript
+interface ClientAvmSigner {
+  address: string;
+  signTransactions(
+    txns: Uint8Array[],
+    indexesToSign?: number[],
+  ): Promise<(Uint8Array | null)[]>;
+}
+```
+
+**For Node.js (private key):**
+```typescript
+import algosdk from "algosdk";
+
+const secretKey = Buffer.from(process.env.AVM_PRIVATE_KEY!, "base64");
+const address = algosdk.encodeAddress(secretKey.slice(32));
+
+const signer = {
+  address,
+  signTransactions: async (txns: Uint8Array[], indexesToSign?: number[]) => {
+    return txns.map((txn, i) => {
+      if (indexesToSign && !indexesToSign.includes(i)) return null;
+      const decoded = algosdk.decodeUnsignedTransaction(txn);
+      const signed = algosdk.signTransaction(decoded, secretKey);
+      return signed.blob;
+    });
+  },
+};
+```
+
+**For Browser (@txnlab/use-wallet):**
+```typescript
+import { useWallet } from "@txnlab/use-wallet-react";
+import type { ClientAvmSigner } from "@x402-avm/avm";
+
+function useAvmSigner(): ClientAvmSigner | null {
+  const { activeAccount, signTransactions } = useWallet();
+  if (!activeAccount) return null;
+  return {
+    address: activeAccount.address,
+    signTransactions: async (txns: Uint8Array[], indexesToSign?: number[]) => {
+      return signTransactions(txns, indexesToSign);
+    },
+  };
+}
+```
+
+### Step 3: Create and Configure the x402Client
+
+```typescript
+import { x402Client } from "@x402-avm/fetch"; // or "@x402-avm/axios"
+import { registerExactAvmScheme } from "@x402-avm/avm/exact/client";
+
+const client = new x402Client();
+registerExactAvmScheme(client, { signer });
+```
+
+### Step 4: Wrap Fetch or Axios
+
+**Fetch:**
+```typescript
+import { wrapFetchWithPayment } from "@x402-avm/fetch";
+
+const fetchWithPay = wrapFetchWithPayment(fetch, client);
+const response = await fetchWithPay("https://api.example.com/premium-data");
+```
+
+**Axios:**
+```typescript
+import axios from "axios";
+import { wrapAxiosWithPayment } from "@x402-avm/axios";
+
+const api = wrapAxiosWithPayment(axios.create(), client);
+const response = await api.get("https://api.example.com/premium-data");
+```
+
+### Step 5: Add Payment Policies (Optional)
+
+Policies filter payment requirements before selection. They are applied in order:
+
+```typescript
+import type { PaymentPolicy } from "@x402-avm/fetch";
+
+const maxAmount: PaymentPolicy = (version, reqs) => {
+  return reqs.filter((r) => BigInt(r.amount ?? "0") <= BigInt("5000000"));
+};
+
+const preferAlgorand: PaymentPolicy = (version, reqs) => {
+  const algoReqs = reqs.filter((r) => r.network.startsWith("algorand:"));
+  return algoReqs.length > 0 ? algoReqs : reqs;
+};
+
+client.registerPolicy(preferAlgorand).registerPolicy(maxAmount);
+```
+
+### Step 6: Add Lifecycle Hooks (Optional)
+
+Monitor and control the payment lifecycle:
+
+```typescript
+client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
+  const amountUSDC = Number(selectedRequirements.amount) / 1_000_000;
+  console.log(`Paying $${amountUSDC.toFixed(6)} USDC`);
+  if (amountUSDC > 10) {
+    return { abort: true, reason: "Amount exceeds $10 limit" };
+  }
+});
+
+client.onAfterPaymentCreation(async () => {
+  console.log("Payment signed successfully");
+});
+
+client.onPaymentCreationFailure(async ({ error }) => {
+  console.error("Payment failed:", error.message);
+});
+```
+
+## Important Rules / Guidelines
+
+1. **Always register a scheme before wrapping** -- `registerExactAvmScheme(client, { signer })` must be called before `wrapFetchWithPayment` or `wrapAxiosWithPayment`
+2. **AVM_PRIVATE_KEY format** -- Base64-encoded 64-byte key (32-byte seed + 32-byte public key)
+3. **Address derivation** -- Always use `algosdk.encodeAddress(secretKey.slice(32))`, never the first 32 bytes
+4. **Single retry** -- The wrapper retries exactly once after 402. If the retry also returns 402, the error is propagated
+5. **Interceptor order for Axios** -- Add your own interceptors first, then call `wrapAxiosWithPayment` last
+6. **Config-based alternative** -- Use `wrapFetchWithPaymentFromConfig` / `wrapAxiosWithPaymentFromConfig` for declarative setup without manual `x402Client` construction
+7. **Wildcard networks** -- Use `"algorand:*"` in config-based setups to match any Algorand network
+
+## Config-Based Setup (Alternative)
+
+Instead of creating an `x402Client` manually, use the config-based approach:
+
+```typescript
+import { wrapFetchWithPaymentFromConfig, type x402ClientConfig } from "@x402-avm/fetch";
+import { ExactAvmScheme } from "@x402-avm/avm";
+
+const config: x402ClientConfig = {
+  schemes: [
+    {
+      network: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+      client: new ExactAvmScheme(signer),
+    },
+  ],
+  policies: [maxAmount],
+};
+
+const fetchWithPay = wrapFetchWithPaymentFromConfig(fetch, config);
+```
+
+## Common Errors / Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Failed to parse payment requirements` | Server returned 402 with invalid body | Check server is running x402-compatible middleware |
+| `Failed to create payment payload` | Insufficient balance or wrong network | Ensure USDC balance on the correct network |
+| `Payment already attempted` | Server returned 402 after payment was sent | Payment was rejected; check facilitator logs |
+| `No network/scheme registered` | Server requires an unregistered network | Register the needed scheme with `registerExactAvmScheme` |
+| `Payment creation aborted` | A `beforePaymentCreation` hook returned abort | Review hook logic; check amount limits |
+| `All payment requirements were filtered out` | Policies removed all options | Relax policies or register additional schemes |
+| `No client registered for x402 version: 2` | No schemes registered at all | Call `registerExactAvmScheme(client, { signer })` |
+
+## Reading Payment Receipts
+
+After a successful paid request, check the response header:
+
+```typescript
+import { decodePaymentResponseHeader } from "@x402-avm/fetch";
+
+const paymentResponseHeader = response.headers.get("PAYMENT-RESPONSE");
+if (paymentResponseHeader) {
+  const receipt = decodePaymentResponseHeader(paymentResponseHeader);
+  console.log("Transaction settled:", receipt);
+}
+```
+
+## References / Further Reading
+
+- [create-typescript-x402-client-reference.md](./create-typescript-x402-client-reference.md) - Detailed API reference
+- [create-typescript-x402-client-examples.md](./create-typescript-x402-client-examples.md) - Complete code examples
+- [x402-avm Fetch Examples](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [x402-avm Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)