From 3ada2b043f95eee74bad157438dd941b1c978c6e Mon Sep 17 00:00:00 2001 From: Dennj Osele Date: Wed, 26 Nov 2025 02:27:15 +0000 Subject: [PATCH] Proposed spec addition for bill/basket support in v2 --- specs/schemes/basket/README.md | 52 +++++++ specs/schemes/basket/basket.schema.json | 42 +++++ specs/schemes/basket/scheme_basket.md | 196 ++++++++++++++++++++++++ 3 files changed, 290 insertions(+) create mode 100644 specs/schemes/basket/README.md create mode 100644 specs/schemes/basket/basket.schema.json create mode 100644 specs/schemes/basket/scheme_basket.md diff --git a/specs/schemes/basket/README.md b/specs/schemes/basket/README.md new file mode 100644 index 000000000..159ead2f4 --- /dev/null +++ b/specs/schemes/basket/README.md @@ -0,0 +1,52 @@ +# Basket Protocol Extension + +This directory contains the specification and schema for the `basket` protocol extension in x402 v2. + +## Files + +- **[scheme_basket.md](scheme_basket.md)**: Full specification with use cases and integration guide +- **[basket.schema.json](basket.schema.json)**: JSON Schema (draft-07) definition + +## Overview + +The `basket` field enables structured, itemized line items in payment requests, allowing clients to render detailed invoices without custom parsing logic. + +### Example + +```json +{ + "basket": [ + { + "name": "Premium Article Access", + "price": "5000000000000000", + "quantity": 1 + }, + { + "name": "API Credits (100 calls)", + "price": "10000000000000000", + "quantity": 2, + "discount": "1000000000000000" + } + ] +} +``` + +## Schema Fields + +Each basket item supports: +- `id` (optional): Unique identifier for the line item (string) +- `name` (required): Human-readable item description +- `price` (required): Amount in smallest asset unit (string) +- `quantity` (optional): Number of units, default 1 +- `tax` (optional): Tax amount per item (string) +- `discount` (optional): Discount amount per item (string) +- `metadata` (optional): Extensible object for additional data + +## Validation + +Use the JSON schema to validate basket data: + +```bash +# Example with ajv-cli +ajv validate -s basket.schema.json -d example-basket.json +``` diff --git a/specs/schemes/basket/basket.schema.json b/specs/schemes/basket/basket.schema.json new file mode 100644 index 000000000..aa1879e2c --- /dev/null +++ b/specs/schemes/basket/basket.schema.json @@ -0,0 +1,42 @@ +{ + "$id": "https://x402.org/spec/v2/basket.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Basket", + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "price" + ], + "properties": { + "id": { + "type": "string", + "description": "Optional unique identifier for the line item. Useful for inventory tracking, refunds, and correlation across requests." + }, + "name": { + "type": "string" + }, + "price": { + "type": "string", + "description": "Amount in the smallest unit of the asset." + }, + "quantity": { + "type": "integer", + "minimum": 1, + "default": 1 + }, + "tax": { + "type": "string" + }, + "discount": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": true + } + }, + "additionalProperties": false + } +} \ No newline at end of file diff --git a/specs/schemes/basket/scheme_basket.md b/specs/schemes/basket/scheme_basket.md new file mode 100644 index 000000000..bf87f46f0 --- /dev/null +++ b/specs/schemes/basket/scheme_basket.md @@ -0,0 +1,196 @@ +# Scheme: `basket` + +## Summary + +The `basket` field is an optional protocol extension that provides a structured, machine-readable representation of itemized line items in a payment request. It enables clients to render detailed invoices, receipts, and shopping carts without custom parsing logic, aligning x402 with modern payment APIs. + +Each item in the basket array includes: +- **id**: Optional unique identifier for the line item (for inventory tracking, refunds, correlation) +- **name**: Human-readable item description +- **price**: Amount in the smallest unit of the asset (e.g., wei, satoshis) +- **quantity**: Number of units (default: 1) +- **tax**: Optional tax amount per item +- **discount**: Optional discount amount per item +- **metadata**: Optional extensible object for additional item data + +The basket field complements the existing `extra` field and is compatible with x402 v2. + +## Use Cases + +### E-commerce Checkout +A merchant selling multiple digital or physical products can provide a detailed breakdown: +```json +{ + "basket": [ + { + "name": "Premium Article Access", + "price": "5000000000000000", + "quantity": 1 + }, + { + "name": "API Credits (100 calls)", + "price": "10000000000000000", + "quantity": 2, + "discount": "1000000000000000" + } + ] +} +``` + +### SaaS Subscriptions +Service providers can itemize subscription components, add-ons, and usage-based charges: +```json +{ + "basket": [ + { + "name": "Pro Plan (Monthly)", + "price": "50000000000000000000", + "quantity": 1 + }, + { + "name": "Additional User Seats", + "price": "10000000000000000000", + "quantity": 3 + }, + { + "name": "Overage Charges", + "price": "5000000000000000000", + "quantity": 1, + "metadata": { + "billing_period": "2025-10", + "usage_gb": 25.5 + } + } + ] +} +``` + +### Tax & Discount Transparency +Financial applications requiring tax and discount breakdowns per item: +```json +{ + "basket": [ + { + "name": "Software License", + "price": "100000000000000000000", + "quantity": 1, + "tax": "8000000000000000000", + "metadata": { + "tax_rate": "0.08", + "jurisdiction": "CA" + } + } + ] +} +``` + +### Grocery Shopping +On-chain grocery payments with itemized receipts showing quantities, prices, and applicable taxes: +```json +{ + "basket": [ + { + "id": "item_bananas_001", + "name": "Organic Bananas (lb)", + "price": "1990000", + "quantity": 3, + "metadata": { + "unit": "lb", + "upc": "4011" + } + }, + { + "id": "item_milk_002", + "name": "Milk - Whole (1 gal)", + "price": "4990000", + "quantity": 2, + "tax": "350000", + "metadata": { + "upc": "041303001264", + "category": "dairy" + } + }, + { + "id": "item_bread_003", + "name": "Bread - Sourdough", + "price": "5490000", + "quantity": 1, + "metadata": { + "upc": "041130563652", + "organic": true + } + }, + { + "id": "item_coffee_004", + "name": "Coffee Beans - Ethiopia (12oz)", + "price": "14990000", + "quantity": 1, + "discount": "2000000", + "metadata": { + "upc": "853045006247", + "member_discount": true + } + } + ] +} +``` + +### Agent-to-Agent Payments +LLM agents purchasing tool access or resources can track itemized costs: +```json +{ + "basket": [ + { + "name": "GPT-4 API Call", + "price": "200000000000000", + "quantity": 15, + "metadata": { + "tokens_used": 4500, + "model": "gpt-4-turbo" + } + } + ] +} +``` + +## Schema Definition + +**Schema URI**: `https://x402.org/spec/v2/basket.schema.json` + +### Validation Rules + +1. **Type**: Array of objects +2. **Required fields per item**: `name`, `price` +3. **Optional fields per item**: `id`, `quantity`, `tax`, `discount`, `metadata` +4. **Price format**: String representation of amount in smallest unit +5. **Quantity**: Integer >= 1 (default: 1) +6. **Item ID**: Optional string for tracking and correlation (follows Stripe pattern) +7. **No additional properties**: Items cannot have fields beyond the defined schema + +### Integration with PaymentRequirements + +When constructing a `PaymentRequirements` response, include the `basket` field alongside the existing `extra` field: + +```typescript +{ + "asset": "0x...", + "amount": "25000000000000000", + "extra": "2 items: Premium Article + API Credits", + "basket": [ + { + "name": "Premium Article Access", + "price": "5000000000000000", + "quantity": 1 + }, + { + "name": "API Credits (100 calls)", + "price": "10000000000000000", + "quantity": 2 + } + ] +} +``` + +### Implementation Notes +- Sum of `(price + tax - discount) * quantity` for all items should equal the total `amount` +- Servers should validate basket totals match the requested amount before returning payment requirements