@circle-fin/x402-batching 2.0.3

package/README.md

@@ -0,0 +1,123 @@
+# x402-batching
+
+**Gasless micropayments via Circle Gateway.**
+
+This SDK allows you to add **gasless payments** to your application using the open [x402 protocol](https://x402.org). Payments are signed off-chain and settled in batches by [Circle Gateway](https://developers.circle.com/gateway).
+
+## Integration at a Glance
+
+### 1. Simple Integration (Express)
+
+Monetize any API route with **2 lines of code**:
+
+```typescript
+// Seller
+const gateway = createGatewayMiddleware({ sellerAddress: '0x...' });
+app.get('/premium', gateway.require('$0.01'), (req, res) => res.json({ ... }));
+```
+
+Pay for it **without gas**:
+
+```typescript
+// Buyer
+const client = new GatewayClient({ chain: 'arcTestnet', privateKey });
+await client.pay('https://api.example.com/premium');
+```
+
+### 2. Using standard @x402/core?
+
+If you already use the standard x402 library, just add Gateway support:
+
+```typescript
+import { x402ResourceServer } from '@x402/core/server';
+import { BatchFacilitatorClient } from '@circle-fin/x402-batching/server';
+
+const server = new x402ResourceServer([
+  // Add Gateway alongside your other facilitators
+  new BatchFacilitatorClient(),
+]);
+
+await server.initialize();
+```
+
+---
+
+## Installation
+
+```bash
+npm install @circle-fin/x402-batching
+```
+
+This will also install the required peer dependencies (`@x402/core`, `viem`). The optional peer dependency `@x402/evm` is only needed if using `CompositeEvmScheme` or `GatewayEvmScheme` — see [Migration Guide](./docs/MIGRATION_GUIDE.md) for details.
+
+---
+
+## Quick Start
+
+Experience the flow immediately with our **Paywall Demo**.
+
+1.  **Clone & Build**
+
+    ```bash
+    git clone https://github.com/crcl-main/x402-batching-sdk-internal.git
+    cd x402-batching-sdk-internal
+    nvm install && nvm use && npm install && npm run build
+    ```
+
+2.  **Run the Demo**
+
+    ```bash
+    cd examples/basic-paywall
+    npm install
+
+    # Terminal 1: Start Seller
+    npm run server
+
+    # Terminal 2: Run Buyer (Requires Testnet USDC)
+    export PRIVATE_KEY=0x...
+    npm run deposit   # One-time deposit
+    npm run client    # Pay for resource gaslessly
+    npm run client    # Pay for resource gaslessly
+    npm run client    # Pay for resource gaslessly
+    ...
+    ```
+
+> **Need Funds?** Get testnet USDC from the [Circle Faucet](https://faucet.circle.com) (Select "Arc Testnet").
+>
+> **Need more?** The public faucet has limits. Use the [Developer Console Faucet API](https://developers.circle.com/w3s/developer-console-faucet#fund-a-wallet-programmatically) with your API key for higher limits:
+>
+> ```bash
+> curl -X POST https://api.circle.com/v1/faucet/drips \
+>   -H 'Authorization: Bearer KEY' -H 'Content-Type: application/json' \
+>   -d '{"address": "0x...", "blockchain": "ARC", "usdc": true}'
+> ```
+
+---
+
+## Documentation
+
+| Guide                                                      | Description                                                  |
+| ---------------------------------------------------------- | ------------------------------------------------------------ |
+| [**Concepts**](./docs/CONCEPTS.md)                         | Understand how gasless payments work.                        |
+| [**Seller Guide**](./docs/SELLER_GUIDE.md)                 | How to monetize your API.                                    |
+| [**Buyer Guide**](./docs/BUYER_GUIDE.md)                   | How to pay for resources and withdraw funds.                 |
+| [**Facilitator Guide**](./docs/FACILITATOR_INTEGRATION.md) | For infrastructure providers to add gasless payment support. |
+| [**SDK Reference**](./docs/SDK_REFERENCE.md)               | Detailed SDK documentation.                                  |
+
+## Supported Networks
+
+Circle Gateway connects multiple blockchains for instant cross-chain liquidity.
+
+- **Gasless Payments**: Currently supported on **[Arc Testnet](https://arc.network)**.
+- **Deposits & Withdrawals**: Supported on many EVM chains.
+
+See [**Networks & Addresses**](./docs/NETWORKS.md) for the full list of chain IDs and contracts.
+
+---
+
+## Try Our Demos
+
+| Demo                                               | Description                                             |
+| -------------------------------------------------- | ------------------------------------------------------- |
+| [**Basic Paywall**](./examples/basic-paywall/)     | Simple E2E example with a Seller API and Buyer script.  |
+| [**Digital Dungeon**](./examples/digital-dungeon/) | Interactive adventure game demonstrating micropayments. |