open-index/open-npm huggingface dataset:
npm package: @nanosession/client
Description: PaymentHandler for NanoSession x402 client
Latest version: 0.2.0

# @nanosession/client

Client-side payment handler for x402 NanoSession — creates and broadcasts Nano payments to satisfy HTTP 402 requirements.

## Installation

```bash
pnpm add @nanosession/client
```

Peer dependencies: `@nanosession/core`, `@nanosession/rpc`

## Usage

```typescript
import { NanoSessionPaymentHandler } from '@nanosession/client';
import { NanoRpcClient } from '@nanosession/rpc';

const rpcClient = new NanoRpcClient({ endpoints: ['https://rpc.nano.to'] });

const paymentHandler = new NanoSessionPaymentHandler({
  rpcClient,
  seed: process.env.NANO_SEED!,
  accountIndex: 0,
});

// Create a payment payload from server-issued requirements
const payload = await paymentHandler.createPayment(paymentRequirements);
```

## API

### `NanoSessionPaymentHandler`

#### Constructor Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `rpcClient` | `NanoRpcClient` | (required) | Nano RPC client for broadcasting blocks |
| `seed` | `string` | (required) | 64-character hex seed for the paying account |
| `accountIndex` | `number` | `0` | BIP44-style account index derived from seed |

#### Methods

- `createPayment(requirements: PaymentRequirements): Promise<PaymentPayload>` — Creates and broadcasts a Nano send block, returns a `PaymentPayload`
- `supports(requirements: PaymentRequirements): boolean` — Returns whether this handler can satisfy given requirements

## Documentation

Full protocol documentation: [https://csi.ninzin.net/x402.NanoSession/](https://csi.ninzin.net/x402.NanoSession/)

## License

MIT
npm package: @nanosession/core
Description: Core types and schema mapping for NanoSession x402 integration
Latest version: 0.2.0

# @nanosession/core

Shared types, constants, builders, and utilities for the NanoSession x402 protocol.

## Installation

```bash
pnpm add @nanosession/core
```

## Usage

```typescript
import { SCHEME, NETWORK, createPaymentRequirements } from '@nanosession/core';
import type { PaymentRequirements, PaymentPayload } from '@nanosession/core';

const requirements = createPaymentRequirements({
  payTo: 'nano_1abc...',
  amountRaw: '1000000000000000000000000000',
  description: 'Access to protected resource',
});
```

## What's Included

- **Constants**: `SCHEME`, `NETWORK`, `ASSET`, `VERSION`, `TAG_MODULUS`, `TAG_MULTIPLIER`
- **Types**: `PaymentRequirements`, `PaymentPayload`, `NanoSessionExtra`, `NanoSignatureExtra`
- **Builders**: `createPaymentRequirements()`, `createPaymentPayload()`, `createPaymentRequired()`
- **Utilities**: `calculateTaggedAmount()`, `deriveAddressFromSeed()`, `assertValidRawAmount()`
- **Extensions**: `payment-identifier` helpers (see x402 Extensions below)

### x402 Extensions

The `payment-identifier` extension allows servers to attach a stable payment ID to a payment requirements object, enabling idempotent payment tracking across requests.

```typescript
import { declarePaymentIdentifierExtension } from '@nanosession/core';

const ext = declarePaymentIdentifierExtension({ required: true });
```

## Documentation

[Full protocol specification and guides](https://csi.ninzin.net/x402.NanoSession/)

## License

MIT
npm package: @nanosession/facilitator
Description: FacilitatorHandler and spent set for NanoSession x402 server
Latest version: 0.2.0

# @nanosession/facilitator

Server-side facilitator handler for x402 NanoSession — verifies and settles Nano payments for HTTP 402 flows.

## Installation

```bash
pnpm add @nanosession/facilitator
```

Peer dependencies: `@nanosession/core`, `@nanosession/rpc`

## Usage

```typescript
import { NanoSessionFacilitatorHandler } from '@nanosession/facilitator';
import { NanoRpcClient } from '@nanosession/rpc';

const rpcClient = new NanoRpcClient({ endpoints: ['https://rpc.nano.to'] });

const facilitator = new NanoSessionFacilitatorHandler({
  rpcClient,
  payTo: 'nano_3your_receiving_address...',
  resourceAmountRaw: '1000000000000000000000000', // 0.001 XNO
});

// Issue payment requirements for a 402 response
const requirements = await facilitator.createRequirements();

// Verify and settle an incoming payment
const result = await facilitator.settle(paymentPayload);
```

## API

### `NanoSessionFacilitatorHandler`

#### Methods

- `createRequirements()` — Generates session-bound payment requirements to include in a 402 response
- `verify(payload)` — Verifies a payment without marking the block hash as spent
- `settle(payload)` — Verifies and settles a payment (marks block hash as spent, preventing reuse)

## Security

NanoSessionFacilitatorHandler uses **session binding** to prevent receipt-stealing attacks — each set of payment requirements includes a unique session ID and tag amount that the client must encode into the Nano send block. An internal **spent set** ensures every block hash can only be accepted once, eliminating replay and double-spend attacks.

## Documentation

Full protocol specification and guides: <https://csi.ninzin.net/x402.NanoSession/>

## License

MIT
npm package: @nanosession/facilitator-service
Description: Production-ready Nano x402 Facilitator service
Latest version: 0.2.0

# @nanosession/facilitator-service

Standalone Express-based facilitator service for x402 NanoSession — a deployable server that verifies and settles Nano payments.

## Installation

```bash
pnpm add @nanosession/facilitator-service
```

## Usage

```bash
# Configure via environment variables
export NANO_RPC_URL=https://rpc.nano.to
export NANO_SEED=your_64_char_hex_seed
export PORT=4000

# Start the service
npx @nanosession/facilitator-service
```

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/supported` | Returns supported payment schemes |
| `POST` | `/verify` | Verifies a payment payload |
| `POST` | `/settle` | Verifies and settles a payment |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `NANO_RPC_URL` | Nano node RPC URL | `https://rpc.nano.to` |
| `NANO_SEED` | 64-char hex wallet seed (optional, for receive mode) | — |
| `NANO_ACCOUNT_INDEX` | HD account index | `0` |
| `PORT` | Server port | `4000` |
| `CORS_ORIGIN` | CORS origin | `*` |

## Documentation

[https://csi.ninzin.net/x402.NanoSession/](https://csi.ninzin.net/x402.NanoSession/)

## License

MIT
npm package: @nanosession/rpc
Description: Nano RPC client with failover support
Latest version: 0.2.0

# @nanosession/rpc

Nano RPC client with multi-endpoint failover and exponential backoff retry.

## Installation

```bash
pnpm add @nanosession/rpc
```

## Usage

```typescript
import { NanoRpcClient } from '@nanosession/rpc';

const client = new NanoRpcClient({
  endpoints: ['https://rpc.nano.to'],
  maxRetries: 3,
  retryDelayMs: 1000,
  timeoutMs: 30000
});

// Get block info
const blockInfo = await client.getBlockInfo('BLOCK_HASH');

// Get account info
const accountInfo = await client.getAccountInfo('nano_address');

// Generate proof-of-work
const work = await client.generateWork('FRONTIER_HASH');
```

## URL Query Parameter Convention

RPC endpoint URLs support query parameters that are **automatically merged into each RPC request body**. This enables API key authentication for paid RPC services:

```typescript
// API key is extracted from URL and merged into every RPC body
const client = new NanoRpcClient({
  endpoints: ['https://rpc.nano.to?key=YOUR_API_KEY']
});

// The request body will include: { action: "block_info", key: "YOUR_API_KEY", ... }
const info = await client.getBlockInfo('HASH');
```

### Multiple Parameters

All query parameters are extracted and merged:

```typescript
const client = new NanoRpcClient({
  endpoints: ['https://rpc.example.com?key=ABC&token=XYZ']
});
// Every request body includes: { ..., key: "ABC", token: "XYZ" }
```

### Failover with Different Credentials

Each endpoint can have its own credentials:

```typescript
const client = new NanoRpcClient({
  endpoints: [
    'https://primary.example.com?key=PRIMARY_KEY',
    'https://backup.example.com?key=BACKUP_KEY'
  ]
});
```

## API

### `NanoRpcClient`

#### Constructor Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `endpoints` | `string[]` | (required) | RPC endpoint URLs (query params extracted and merged into body) |
| `maxRetries` | `number` | `3` | Maximum retries per endpoint |
| `retryDelayMs` | `number` | `1000` | Initial retry delay (doubles each retry) |
| `timeoutMs` | `number` | `30000` | Request timeout in milliseconds |

#### Methods

- `getBlockInfo(hash: string): Promise<BlockInfo>` - Get block information by hash
- `receivableExists(hash: string): Promise<boolean>` - Check if a send block is still receivable
- `confirmBlock(hash: string): Promise<void>` - Trigger election for a block
- `getAccountInfo(address: string): Promise<AccountInfo>` - Get account information
- `getAccountHistory(account: string, count?: number): Promise<AccountHistoryEntry[]>` - Get transaction history
- `processBlock(block: Record<string, unknown>): Promise<string>` - Broadcast a signed block
- `generateWork(hash: string, difficulty?: string): Promise<string>` - Request PoW generation
- `getActiveDifficulty(): Promise<string \| undefined>` - Get current network difficulty

## Documentation

Full protocol specification and guides: <https://csi.ninzin.net/x402.NanoSession/>

## License

MIT