openclaw-algorand-plugin 0.5.0

package/skills/algorand-x402-python/references/use-python-x402-core-avm-reference.md

@@ -0,0 +1,278 @@
+# x402-avm Python Core and AVM Mechanism Reference
+
+Detailed API reference for the x402-avm Python package core components and AVM mechanism.
+
+## Core Package Exports
+
+### Client Components
+
+| Export | Import | Description |
+|--------|--------|-------------|
+| `x402Client` | `from x402 import x402Client` | Async client that handles 402 responses automatically |
+| `x402ClientSync` | `from x402 import x402ClientSync` | Synchronous variant of x402Client |
+
+### Server Components
+
+| Export | Import | Description |
+|--------|--------|-------------|
+| `x402ResourceServer` | `from x402 import x402ResourceServer` | Async resource server with payment middleware |
+| `x402ResourceServerSync` | `from x402 import x402ResourceServerSync` | Synchronous variant |
+
+### Facilitator Components
+
+| Export | Import | Description |
+|--------|--------|-------------|
+| `x402Facilitator` | `from x402 import x402Facilitator` | Async facilitator for payment verification and settlement |
+| `x402FacilitatorSync` | `from x402 import x402FacilitatorSync` | Synchronous variant |
+
+### Schema Types
+
+| Export | Import | Description |
+|--------|--------|-------------|
+| `PaymentRequirements` | `from x402.schemas import PaymentRequirements` | V2 payment requirements structure |
+| `PaymentPayload` | `from x402.schemas import PaymentPayload` | Payment payload sent in PAYMENT-SIGNATURE header |
+| `Network` | `from x402.schemas import Network` | Network identifier type (CAIP-2 string) |
+
+---
+
+## AVM Mechanism Exports
+
+### Signer Protocols
+
+| Export | Import | Description |
+|--------|--------|-------------|
+| `ClientAvmSigner` | `from x402.mechanisms.avm.signer import ClientAvmSigner` | Protocol for client-side transaction signing |
+| `FacilitatorAvmSigner` | `from x402.mechanisms.avm.signer import FacilitatorAvmSigner` | Protocol for facilitator-side operations |
+
+### Scheme Classes
+
+| Export | Import | Description |
+|--------|--------|-------------|
+| `ExactAvmScheme` | `from x402.mechanisms.avm.exact import ExactAvmScheme` | Base AVM exact payment scheme |
+| `ExactAvmClientScheme` | `from x402.mechanisms.avm.exact import ExactAvmClientScheme` | Client-specific scheme |
+| `ExactAvmServerScheme` | `from x402.mechanisms.avm.exact import ExactAvmServerScheme` | Server-specific scheme |
+| `ExactAvmFacilitatorScheme` | `from x402.mechanisms.avm.exact import ExactAvmFacilitatorScheme` | Facilitator-specific scheme |
+
+### Registration Functions
+
+| Function | Import | Description |
+|----------|--------|-------------|
+| `register_exact_avm_client` | `from x402.mechanisms.avm.exact import register_exact_avm_client` | Register AVM on a client |
+| `register_exact_avm_server` | `from x402.mechanisms.avm.exact import register_exact_avm_server` | Register AVM on a server |
+| `register_exact_avm_facilitator` | `from x402.mechanisms.avm.exact import register_exact_avm_facilitator` | Register AVM on a facilitator |
+
+---
+
+## Constants Reference
+
+### Network Identifiers
+
+| Constant | Value | Import |
+|----------|-------|--------|
+| `ALGORAND_MAINNET_CAIP2` | `"algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="` | `from x402.mechanisms.avm.constants import ALGORAND_MAINNET_CAIP2` |
+| `ALGORAND_TESTNET_CAIP2` | `"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` | `from x402.mechanisms.avm.constants import ALGORAND_TESTNET_CAIP2` |
+| `SUPPORTED_NETWORKS` | `[MAINNET_CAIP2, TESTNET_CAIP2]` | `from x402.mechanisms.avm.constants import SUPPORTED_NETWORKS` |
+
+### Genesis Hashes
+
+| Constant | Value |
+|----------|-------|
+| `MAINNET_GENESIS_HASH` | `"wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="` |
+| `TESTNET_GENESIS_HASH` | `"SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` |
+
+### V1 Compatibility
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `V1_NETWORKS` | `["algorand-mainnet", "algorand-testnet"]` | Legacy network names |
+| `V1_TO_V2_NETWORK_MAP` | `{"algorand-mainnet": CAIP2, ...}` | V1 to CAIP-2 mapping |
+| `V2_TO_V1_NETWORK_MAP` | `{CAIP2: "algorand-mainnet", ...}` | CAIP-2 to V1 mapping |
+
+### USDC Configuration
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `USDC_MAINNET_ASA_ID` | `31566704` | Mainnet USDC ASA ID |
+| `USDC_TESTNET_ASA_ID` | `10458941` | Testnet USDC ASA ID |
+| `DEFAULT_DECIMALS` | `6` | USDC decimal places |
+
+### Transaction Limits
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `MAX_GROUP_SIZE` | `16` | Maximum transactions in an atomic group |
+| `MIN_TXN_FEE` | `1000` | Minimum transaction fee in microAlgos |
+
+### Algod Endpoints
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `FALLBACK_ALGOD_MAINNET` | `"https://mainnet-api.algonode.cloud"` | Default mainnet Algod URL |
+| `FALLBACK_ALGOD_TESTNET` | `"https://testnet-api.algonode.cloud"` | Default testnet Algod URL |
+| `MAINNET_ALGOD_URL` | `env ALGOD_MAINNET_URL` or fallback | Resolved mainnet URL |
+| `TESTNET_ALGOD_URL` | `env ALGOD_TESTNET_URL` or fallback | Resolved testnet URL |
+| `MAINNET_INDEXER_URL` | `env` or AlgoNode | Mainnet indexer URL |
+| `TESTNET_INDEXER_URL` | `env` or AlgoNode | Testnet indexer URL |
+
+### NETWORK_CONFIGS Structure
+
+```python
+NETWORK_CONFIGS = {
+    ALGORAND_TESTNET_CAIP2: {
+        "algod_url": "https://testnet-api.algonode.cloud",
+        "indexer_url": "https://testnet-idx.algonode.cloud",
+        "genesis_hash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+        "genesis_id": "testnet-v1.0",
+        "default_asset": {"asa_id": 10458941, "name": "USDC", "decimals": 6},
+    },
+    ALGORAND_MAINNET_CAIP2: {
+        "algod_url": "https://mainnet-api.algonode.cloud",
+        "indexer_url": "https://mainnet-idx.algonode.cloud",
+        "genesis_hash": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
+        "genesis_id": "mainnet-v1.0",
+        "default_asset": {"asa_id": 31566704, "name": "USDC", "decimals": 6},
+    },
+}
+```
+
+---
+
+## Utility Functions Reference
+
+### Address Validation
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `is_valid_address` | `(address: str) -> bool` | Validate 58-character Algorand address |
+
+### Amount Conversion
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `to_atomic_amount` | `(amount: float, decimals: int = 6) -> int` | Convert decimal to atomic units |
+| `from_atomic_amount` | `(amount: int, decimals: int = 6) -> float` | Convert atomic units to decimal |
+
+### Transaction Encoding/Decoding
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `decode_transaction_bytes` | `(raw_bytes: bytes) -> DecodedTransactionInfo` | Decode raw msgpack transaction |
+| `decode_base64_transaction` | `(b64_str: str) -> DecodedTransactionInfo` | Decode base64-encoded transaction |
+| `decode_payment_group` | `(payment_group: list[str], payment_index: int) -> DecodedGroupInfo` | Decode a full payment group |
+| `encode_transaction_group` | `(raw_bytes_list: list[bytes]) -> list[str]` | Encode transaction list to base64 |
+
+### DecodedTransactionInfo Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `str` | Transaction type: `"pay"`, `"axfer"`, `"appl"`, etc. |
+| `sender` | `str` | Sender Algorand address |
+| `receiver` | `str` or `None` | Receiver address (payments/transfers) |
+| `fee` | `int` | Transaction fee in microAlgos |
+| `is_signed` | `bool` | Whether the transaction is signed |
+| `asset_amount` | `int` or `None` | Asset amount (for asset transfers) |
+| `asset_id` | `int` or `None` | ASA ID (for asset transfers) |
+
+### DecodedGroupInfo Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `transactions` | `list[DecodedTransactionInfo]` | All decoded transactions |
+| `group_id` | `str` | Base64-encoded group ID |
+| `total_fee` | `int` | Sum of all transaction fees |
+| `has_fee_payer` | `bool` | Whether a fee payer transaction is detected |
+| `fee_payer_index` | `int` or `None` | Index of the fee payer transaction |
+
+### Network Utilities
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `normalize_network` | `(network: str) -> str` | Convert V1 name or CAIP-2 to CAIP-2 |
+| `is_valid_network` | `(network: str) -> bool` | Check if network is supported |
+| `get_network_config` | `(network: str) -> dict` | Get full network configuration |
+| `get_usdc_asa_id` | `(network: str) -> int` | Get USDC ASA ID for network |
+| `get_genesis_hash` | `(network: str) -> str` | Get genesis hash for network |
+| `network_from_genesis_hash` | `(hash: str) -> str` | Resolve CAIP-2 from genesis hash |
+
+### Security Validation
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `validate_no_security_risks` | `(info: DecodedTransactionInfo) -> str or None` | Check for rekey, close-to, blocked types |
+| `validate_fee_payer_transaction` | `(info: DecodedTransactionInfo, expected_fee_payer: str) -> str or None` | Validate fee payer txn structure |
+| `is_blocked_transaction_type` | `(type: str) -> bool` | Check if transaction type is blocked |
+
+---
+
+## Encoding Boundary Patterns
+
+The Python `algosdk` (v2.11.1) uses base64 strings at API boundaries, while the x402 SDK protocol uses raw bytes internally:
+
+| Direction | Pattern |
+|-----------|---------|
+| Raw bytes to algosdk | `encoding.msgpack_decode(base64.b64encode(raw_bytes).decode("utf-8"))` |
+| algosdk to raw bytes | `base64.b64decode(encoding.msgpack_encode(obj))` |
+| Sign transaction | `txn_obj.sign(base64.b64encode(secret_key).decode())` |
+| Address from key | `encoding.encode_address(secret_key[32:])` |
+
+### Comparison with TypeScript algosdk
+
+| Operation | Python algosdk | TypeScript algosdk |
+|-----------|---------------|-------------------|
+| Decode unsigned txn | `msgpack_decode(base64_string)` | `decodeUnsignedTransaction(Uint8Array)` |
+| Encode txn | `msgpack_encode(obj)` returns base64 | `txn.toByte()` returns `Uint8Array` |
+| Sign | `txn.sign(base64_key_string)` | `signTransaction(txn, Uint8Array)` |
+
+---
+
+## Fee Abstraction Flow
+
+Fee abstraction uses Algorand atomic transaction groups with pooled fees:
+
+```
+Step 1: Create 2-txn atomic group
+  Txn 0: USDC transfer (sender -> receiver, fee = 0)
+  Txn 1: Self-payment (fee_payer -> fee_payer, fee = 2 * MIN_TXN_FEE)
+
+Step 2: Assign group ID
+  gid = calculate_group_id([txn_0, txn_1])
+  txn_0.group = gid
+  txn_1.group = gid
+
+Step 3: Client signs Txn 0, leaves Txn 1 unsigned
+Step 4: Client sends paymentGroup = [signed_txn_0, unsigned_txn_1]
+Step 5: Facilitator signs Txn 1, submits atomic group
+Step 6: Both execute atomically (all-or-nothing)
+```
+
+**Security guarantees:**
+- Fee payer Txn 1 must be a self-payment (receiver == sender) with amount == 0
+- No rekey, close-to, or other dangerous fields
+- Fee is capped at a reasonable maximum
+- Atomic group ensures all-or-nothing execution
+
+---
+
+## Installation
+
+```bash
+# Core + AVM mechanism
+pip install "x402-avm[avm]"
+
+# With web framework
+pip install "x402-avm[avm,fastapi]"
+pip install "x402-avm[avm,flask]"
+
+# Multi-chain
+pip install "x402-avm[all]"
+```
+
+---
+
+## External Resources
+
+- [x402-avm Examples Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [x402-avm AVM Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)
+- [algosdk Python SDK](https://py-algorand-sdk.readthedocs.io/)
+- [Algorand Developer Portal](https://developer.algorand.org/)
+- [CAIP-2 Chain ID Specification](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md)

package/skills/algorand-x402-python/references/use-python-x402-core-avm.md

@@ -0,0 +1,166 @@
+# Using x402-avm Python Core and AVM Mechanism
+
+Use the x402-avm Python package core components and AVM mechanism directly for building custom payment integrations on Algorand.
+
+## Prerequisites
+
+Before using this skill, ensure:
+
+1. **Python 3.10+** is installed
+2. **x402-avm package** is available: `pip install "x402-avm[avm]"`
+3. **Understanding of x402 payment flow** -- client sends payment, server returns 402, facilitator verifies/settles
+
+## Core Architecture
+
+The x402-avm Python SDK has two layers:
+
+```
+x402-avm Core                          AVM Mechanism
++----------------------------------+   +----------------------------------+
+| x402Client / x402ClientSync      |   | ClientAvmSigner (Protocol)       |
+| x402ResourceServer / ...Sync     |   | FacilitatorAvmSigner (Protocol)  |
+| x402Facilitator / ...Sync        |   | ExactAvmScheme                   |
+| schemas, types                   |   | constants, utils                 |
++----------------------------------+   +----------------------------------+
+         |                                        |
+         +--- register_exact_avm_* ---------------+
+```
+
+## How to Proceed
+
+### Step 1: Install the Package
+
+```bash
+# Core + AVM mechanism
+pip install "x402-avm[avm]"
+
+# With a web framework
+pip install "x402-avm[avm,fastapi]"
+pip install "x402-avm[avm,flask]"
+```
+
+### Step 2: Understand the Signer Protocols
+
+The SDK defines signer protocols (structural typing -- no inheritance required) that separate protocol definitions from implementations.
+
+**ClientAvmSigner** -- for clients making payments:
+
+```python
+from x402.mechanisms.avm.signer import ClientAvmSigner
+
+class ClientAvmSigner(Protocol):
+    @property
+    def address(self) -> str:
+        """58-character Algorand address."""
+        ...
+
+    def sign_transactions(
+        self,
+        unsigned_txns: list[bytes],
+        indexes_to_sign: list[int],
+    ) -> list[bytes | None]:
+        """Sign specified transactions in a group."""
+        ...
+```
+
+**FacilitatorAvmSigner** -- for facilitators verifying/settling payments:
+
+```python
+from x402.mechanisms.avm.signer import FacilitatorAvmSigner
+
+class FacilitatorAvmSigner(Protocol):
+    def get_addresses(self) -> list[str]: ...
+    def sign_transaction(self, txn_bytes: bytes, fee_payer: str, network: str) -> bytes: ...
+    def sign_group(self, group_bytes: list[bytes], fee_payer: str, indexes_to_sign: list[int], network: str) -> list[bytes]: ...
+    def simulate_group(self, group_bytes: list[bytes], network: str) -> None: ...
+    def send_group(self, group_bytes: list[bytes], network: str) -> str: ...
+    def confirm_transaction(self, txid: str, network: str, rounds: int = 4) -> None: ...
+```
+
+### Step 3: Use Constants
+
+```python
+from x402.mechanisms.avm.constants import (
+    ALGORAND_TESTNET_CAIP2,     # "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="
+    ALGORAND_MAINNET_CAIP2,     # "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="
+    USDC_TESTNET_ASA_ID,        # 10458941
+    USDC_MAINNET_ASA_ID,        # 31566704
+    MIN_TXN_FEE,                # 1000
+    MAX_GROUP_SIZE,             # 16
+    NETWORK_CONFIGS,
+)
+```
+
+### Step 4: Use Utility Functions
+
+```python
+from x402.mechanisms.avm.utils import (
+    is_valid_address,
+    to_atomic_amount,
+    from_atomic_amount,
+    decode_transaction_bytes,
+    normalize_network,
+    get_usdc_asa_id,
+)
+
+# Validate address
+is_valid_address("AAAA...")  # True/False
+
+# Convert amounts
+to_atomic_amount(1.50)     # 1500000
+from_atomic_amount(100000) # 0.1
+
+# Decode transactions
+info = decode_transaction_bytes(raw_txn_bytes)
+print(info.type, info.sender, info.fee, info.is_signed)
+```
+
+### Step 5: Register Schemes
+
+```python
+from x402 import x402Client
+from x402.mechanisms.avm.exact import register_exact_avm_client
+
+client = x402Client()
+register_exact_avm_client(client, signer)
+
+# Now client.fetch() handles 402 responses automatically
+response = await client.fetch("https://api.example.com/paid-resource")
+```
+
+### Step 6: Understand Fee Abstraction
+
+Fee abstraction uses Algorand's atomic transaction groups and pooled fees:
+
+```
+Transaction 0: USDC transfer (client -> resource owner, fee = 0)
+Transaction 1: Self-payment (fee payer -> fee payer, fee covers both txns)
+
+Client signs Txn 0, Facilitator signs Txn 1
+Both execute atomically (all-or-nothing)
+```
+
+## Important Rules / Guidelines
+
+1. **Signer separation** -- Protocol definitions live in the SDK (`signer.py`), implementations live in examples. Zero algosdk imports in SDK core.
+2. **First-class AVM** -- AVM is treated identically to EVM/SVM. Never conditional, always registered unconditionally.
+3. **algosdk encoding boundaries** -- `msgpack_decode()` expects base64 string. `msgpack_encode()` returns base64 string. The SDK protocol passes raw msgpack bytes between methods. Convert at boundaries.
+4. **Import constants from SDK** -- Use `ALGORAND_TESTNET_CAIP2` from imports, not hardcoded strings, in SDK code.
+5. **Raw bytes contract** -- The x402 SDK passes raw msgpack bytes between signer methods. This matches the @txnlab/use-wallet ecosystem standard.
+
+## Common Errors / Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `ImportError: x402.mechanisms.avm` | Missing `[avm]` extra | Install with `pip install "x402-avm[avm]"` |
+| `msgpack_decode expects string` | Passing raw bytes | Wrap: `base64.b64encode(raw).decode()` |
+| `Invalid address` | Wrong address format | Must be 58-character Algorand address |
+| `to_atomic_amount overflow` | Value too large | Check decimal places (6 for USDC/ALGO) |
+| `Network not supported` | Unregistered network | Register with `register_exact_avm_*` first |
+
+## References / Further Reading
+
+- [use-python-x402-core-avm-reference.md](./use-python-x402-core-avm-reference.md) -- Detailed API reference for all exports
+- [use-python-x402-core-avm-examples.md](./use-python-x402-core-avm-examples.md) -- Complete code examples
+- [x402-avm AVM Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)
+- [Examples Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)

package/skills/algorand-x402-typescript/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: algorand-x402-typescript
+description: Comprehensive guide for building x402 HTTP-native payment applications on Algorand using TypeScript. This is the parent skill that aggregates all TypeScript x402 sub-skills. Use when working with x402 payments in TypeScript/JavaScript, building clients, servers, facilitators, paywalls, or Next.js apps with Algorand x402, or when explaining x402 concepts to TypeScript developers. Strong triggers include "x402 TypeScript", "x402 Algorand TypeScript", "@x402-avm", "payment protocol TypeScript", "402 payment TypeScript", "x402 client fetch axios", "x402 server express hono", "x402 facilitator TypeScript", "x402 paywall", "x402 Next.js", "x402 core avm TypeScript", "explain x402 TypeScript", "teach x402".
+---
+
+# x402 on Algorand - TypeScript
+
+This is the aggregated parent skill for all x402 HTTP-native payment protocol skills targeting TypeScript/JavaScript. Use the reference files below to find detailed guidance for each component.
+
+## TypeScript Quick Start
+
+```bash
+# Core + AVM mechanism
+npm install @x402-avm/core @x402-avm/avm algosdk
+
+# Server middleware (pick one)
+npm install @x402-avm/express    # Express.js
+npm install @x402-avm/hono       # Hono
+npm install @x402-avm/next       # Next.js
+
+# Client (pick one)
+npm install @x402-avm/fetch      # Fetch API
+npm install @x402-avm/axios      # Axios
+```
+
+### Register AVM Scheme
+
+Every component registers the AVM exact scheme unconditionally — no environment variable guards:
+
+```typescript
+// Client
+import { registerExactAvmScheme } from "@x402-avm/avm/exact/client";
+registerExactAvmScheme(client, { signer });
+
+// Server
+import { registerExactAvmScheme } from "@x402-avm/avm/exact/server";
+registerExactAvmScheme(server);
+
+// Facilitator
+import { registerExactAvmScheme } from "@x402-avm/avm/exact/facilitator";
+registerExactAvmScheme(facilitator, { signer, networks: ALGORAND_TESTNET_CAIP2 });
+```
+
+### TypeScript algosdk Encoding
+
+TypeScript algosdk works with raw `Uint8Array` directly — no conversion needed. This matches the `@txnlab/use-wallet` ecosystem standard. Encoding/decoding to/from base64 happens only at protocol boundaries (PAYMENT-SIGNATURE header serialization).
+
+## Reference Guide
+
+Navigate to the appropriate reference based on your task. Each topic has three files:
+- **`{name}.md`** — Step-by-step implementation guide
+- **`{name}-reference.md`** — API details and type signatures
+- **`{name}-examples.md`** — Complete, runnable code samples
+
+### Explaining x402 for TypeScript
+
+Understand @x402-avm/* TypeScript package structure, signer interfaces (ClientAvmSigner, FacilitatorAvmSigner), registration patterns, builder patterns, constants, and utilities.
+
+- [explain-algorand-x402-typescript.md](./references/explain-algorand-x402-typescript.md) — Package ecosystem explanation
+- [explain-algorand-x402-typescript-reference.md](./references/explain-algorand-x402-typescript-reference.md) — API reference for @x402-avm/* packages
+- [explain-algorand-x402-typescript-examples.md](./references/explain-algorand-x402-typescript-examples.md) — TypeScript pattern examples
+
+### Building Clients
+
+Build HTTP clients with Fetch or Axios that automatically handle 402 payments. Covers wrapFetchWithPayment, wrapAxiosWithPayment, ClientAvmSigner for browser wallets or Node.js private keys.
+
+- [create-typescript-x402-client.md](./references/create-typescript-x402-client.md) — Client creation guide
+- [create-typescript-x402-client-reference.md](./references/create-typescript-x402-client-reference.md) — Fetch/Axios API reference
+- [create-typescript-x402-client-examples.md](./references/create-typescript-x402-client-examples.md) — Client code examples
+
+### Building Servers
+
+Build payment-protected servers with Express.js or Hono middleware. Covers route pricing, multi-network support (AVM+EVM+SVM), 402 responses, and dynamic pricing.
+
+- [create-typescript-x402-server.md](./references/create-typescript-x402-server.md) — Server creation guide
+- [create-typescript-x402-server-reference.md](./references/create-typescript-x402-server-reference.md) — Express/Hono middleware API reference
+- [create-typescript-x402-server-examples.md](./references/create-typescript-x402-server-examples.md) — Server code examples
+
+### Building Next.js Apps
+
+Build fullstack Next.js apps with x402 payment protection using paymentProxy and withX402. Covers App Router integration, middleware-level protection, and per-endpoint control.
+
+- [create-typescript-x402-nextjs.md](./references/create-typescript-x402-nextjs.md) — Next.js integration guide
+- [create-typescript-x402-nextjs-reference.md](./references/create-typescript-x402-nextjs-reference.md) — Next.js API reference
+- [create-typescript-x402-nextjs-examples.md](./references/create-typescript-x402-nextjs-examples.md) — Next.js code examples
+
+### Building Facilitators and Bazaar Discovery
+
+Build facilitator services that verify and settle Algorand payments on-chain. Covers FacilitatorAvmSigner, Express.js facilitator servers, and Bazaar discovery extension for API cataloging (bazaarResourceServerExtension, withBazaar, declare_discovery_extension on servers).
+
+- [create-typescript-x402-facilitator.md](./references/create-typescript-x402-facilitator.md) — Facilitator creation guide (includes Bazaar setup in Step 5)
+- [create-typescript-x402-facilitator-reference.md](./references/create-typescript-x402-facilitator-reference.md) — Facilitator + Bazaar API reference
+- [create-typescript-x402-facilitator-examples.md](./references/create-typescript-x402-facilitator-examples.md) — Facilitator + Bazaar code examples
+
+### Building Paywalls
+
+Build browser paywall UIs with server-side middleware and client-side wallet integration (Pera, Defly, Lute). Covers PaywallBuilder, avmPaywall, multi-network paywalls.
+
+- [create-typescript-x402-paywall.md](./references/create-typescript-x402-paywall.md) — Paywall creation guide
+- [create-typescript-x402-paywall-reference.md](./references/create-typescript-x402-paywall-reference.md) — Paywall API reference
+- [create-typescript-x402-paywall-examples.md](./references/create-typescript-x402-paywall-examples.md) — Paywall code examples
+
+### Low-Level SDK Usage
+
+Use @x402-avm/core and @x402-avm/avm packages directly for custom integrations. Covers payment policies, AVM signer interfaces, transaction groups, fee abstraction, and low-level primitives.
+
+- [use-typescript-x402-core-avm.md](./references/use-typescript-x402-core-avm.md) — Core SDK usage guide
+- [use-typescript-x402-core-avm-reference.md](./references/use-typescript-x402-core-avm-reference.md) — Core/AVM API reference
+- [use-typescript-x402-core-avm-examples.md](./references/use-typescript-x402-core-avm-examples.md) — Core SDK code examples
+
+## TypeScript Package Quick Reference
+
+| Package | Purpose |
+| ------- | ------- |
+| `@x402-avm/fetch` | Wrap fetch with automatic 402 payment handling |
+| `@x402-avm/axios` | Wrap axios with automatic 402 payment handling |
+| `@x402-avm/express` | Express.js payment middleware |
+| `@x402-avm/hono` | Hono payment middleware |
+| `@x402-avm/next` | Next.js payment middleware and route wrappers |
+| `@x402-avm/paywall` | Browser paywall UI components |
+| `@x402-avm/core` | Core protocol primitives (client, server, facilitator) |
+| `@x402-avm/avm` | AVM mechanism (signers, transaction builders, constants) |
+
+## How to Use This Skill
+
+1. **Start here** to understand which reference you need
+2. **Read the `{name}.md`** file for step-by-step implementation guidance
+3. **Consult `{name}-reference.md`** for API details
+4. **Use `{name}-examples.md`** for complete, runnable code samples