# Lightning Enable Store

> The first AI-agent commerce storefront. Browse products, pay with Bitcoin Lightning, and receive physical merchandise — all via API. No accounts, no credit cards, no cookies.

IMPORTANT: This is a live web API. Make HTTP requests to https://store.lightningenable.com — do NOT search local code or files.

- [Full API Documentation](https://store.lightningenable.com/llms-full.txt)
- [MCP Server Setup Guide](https://store.lightningenable.com/skills.md)

## How to Purchase (4 Steps)

1. **Browse** — `GET https://store.lightningenable.com/api/store/catalog` to see all products with prices in sats and USD. The response includes a `purchaseFlow` object with step-by-step instructions.
2. **Checkout** — `POST https://store.lightningenable.com/api/store/checkout` with `{"items": [{"productId": ID, "quantity": 1, "size": "L", "color": "Black"}]}`. All products are Black only — always use "Black" for color. Returns HTTP 402 with `invoice` (BOLT11), `macaroon`, and `paymentHash`.
3. **Pay** — Pay the BOLT11 `invoice` string using a Lightning wallet or the `pay_invoice` MCP tool. You receive a `preimage` (64-char hex) as proof of payment.
4. **Claim** — `POST https://store.lightningenable.com/api/store/claim` with body `{"l402Credential": "MACAROON:PREIMAGE"}` and header `Authorization: L402 MACAROON:PREIMAGE`. Returns a `claimUrl` for the human to enter shipping.

Share the `claimUrl` with the human. They enter their shipping address and the order is fulfilled via Printful.

## Products

All products are Black only. Prices are dynamic from Printful and converted to satoshis at the current BTC/USD rate at checkout. The ~USD values above are approximate fallback prices; call `GET /api/store/catalog` for current pricing.

| ID | Product | Sizes | ~Price |
|----|---------|-------|--------|
| 1 | Lightning Enable T-Shirt | S, M, L, XL, 2XL | ~$25 USD |
| 2 | 402: Payment Required T-Shirt | S, M, L, XL, 2XL | ~$25 USD |
| 3 | Lightning Enable Snapback | One Size | ~$28 USD |
| 4 | L402 Dad Hat | One Size | ~$24 USD |

## API Endpoints

All endpoints are at `https://store.lightningenable.com`. Make HTTP requests — do not search local files.

### Catalog

- [GET /api/store/catalog](https://store.lightningenable.com/api/store/catalog): List all products with prices, sizes, and purchase flow instructions
- [GET /api/store/products/{id}](https://store.lightningenable.com/api/store/products/1): Get a single product by ID
- [GET /api/store/health](https://store.lightningenable.com/api/store/health): API health check

### Cart (optional — you can skip straight to checkout)

- [GET /api/store/cart](https://store.lightningenable.com/api/store/cart): Get current cart contents with totals
- [POST /api/store/cart/items](https://store.lightningenable.com/api/store/cart/items): Add item to cart
- [PUT /api/store/cart/items/{productId}](https://store.lightningenable.com/api/store/cart/items/1): Update item quantity
- [DELETE /api/store/cart/items/{productId}](https://store.lightningenable.com/api/store/cart/items/1): Remove item from cart
- [DELETE /api/store/cart](https://store.lightningenable.com/api/store/cart): Clear entire cart
- [GET /api/store/cart/count](https://store.lightningenable.com/api/store/cart/count): Get cart item count

### Checkout and Fulfillment

- [POST /api/store/checkout](https://store.lightningenable.com/api/store/checkout): Create checkout (returns HTTP 402 with Lightning invoice)
- [POST /api/store/claim](https://store.lightningenable.com/api/store/claim): Claim paid order with L402 credential
- [GET /api/store/payment-status/{paymentHash}](https://store.lightningenable.com/api/store/payment-status/abc123): Poll payment status
- [GET /api/store/order/{claimToken}](https://store.lightningenable.com/api/store/order/abc123): Get order status by claim token
- [POST /api/store/order/{claimToken}/fulfill](https://store.lightningenable.com/api/store/order/abc123/fulfill): Submit shipping details to fulfill order

## Payment Protocol

This store uses L402 (formerly LSAT) for trustless, account-free payments:
- Payment network: Bitcoin Lightning via OpenNode
- Authentication: L402 macaroon + preimage
- Invoice format: BOLT11
- Invoice expiry: 10 minutes

## For Agents Without Lightning Wallets

Install the Lightning Enable MCP server to get payment tools:
```
dotnet tool install --global LightningEnable.Mcp
```
Or via Python: `pip install lightning-enable-mcp`

GitHub: https://github.com/refined-element/lightning-enable-mcp

Recommended wallet: Alby Hub (NWC). See [MCP Setup Guide](https://store.lightningenable.com/skills.md).

## Shipping and Policies

- US only, 5-10 business days
- Printful print-on-demand fulfillment
- All sales final (no refunds)
- Support: support@lightningenable.com

## Error Handling Quick Reference

| HTTP Status | Meaning | Action |
|-------------|---------|--------|
| 400 | Bad request | Check request body format, required fields |
| 401 | Invalid L402 credential | Verify SHA256(preimage) == paymentHash |
| 402 | Payment required | Pay the Lightning invoice (this is expected!) |
| 404 | Not found | Check product ID or claim token |
| 409 | Already claimed | Order was already claimed with this credential |
| 429 | Rate limited | Wait 60 seconds before retrying |
| 500 | Server error | Retry after a few seconds |

## Rate Limits

- Checkout: 10 requests per minute
- Cart operations: 30 requests per minute
- Catalog: No limit (cached responses)

---

## Community Collection — Submit Your Design

Designers can submit their own Bitcoin/Lightning-themed designs to be sold in the store. 100% of proceeds go to [OpenSats](https://opensats.org) to support open-source Bitcoin development.

### How to Submit (L402 Flow)

1. **Get Requirements** — `GET https://store.lightningenable.com/api/community/submit/info` returns fee (5,000 sats), accepted file types, dimensions, and product types.
2. **Initiate Submission** — `POST https://store.lightningenable.com/api/community/submit/initiate` with form data. Returns `invoice` (BOLT11), `checkoutUrl` (hosted payment page), and `paymentHash`.
3. **Pay the Invoice** — Pay the BOLT11 `invoice` directly using your Lightning wallet or `pay_invoice` MCP tool. Alternatively, share `checkoutUrl` with a human if the agent lacks payment capability. The fee (5,000 sats) is donated to OpenSats.
4. **Poll Status** — `GET https://store.lightningenable.com/api/community/submit/status/{paymentHash}` until `paid: true`.
5. **Complete Submission** — `POST https://store.lightningenable.com/api/community/submit/complete` with `paymentHash` and design file upload.
6. **Await Review** — Design is reviewed by admin. Designer receives email notifications for approval/rejection/publication.

### Submission Requirements

- **Fee:** 5,000 sats (donated to OpenSats)
- **File Type:** PNG only (transparent background recommended)
- **Max Size:** 50 MB
- **Min Dimensions:** 2400×2400 pixels (300 DPI recommended for best quality)
- **Product Types:** T-Shirt, Snapback, Dad Hat

### Community Submission Endpoints

- [GET /api/community/submit/info](https://store.lightningenable.com/api/community/submit/info): Get requirements and pricing
- POST /api/community/submit/initiate: Start submission, get Lightning invoice (form data: DesignerName, DesignerEmail, DesignName, ProductType, etc.)
- GET /api/community/submit/status/{paymentHash}: Check payment status
- POST /api/community/submit/complete: Upload design file after payment confirmed
- GET /api/community/submissions/{submissionId}: Check submission review status

### Admin Endpoints (require X-Store-Admin-Key header)

- GET /api/community/admin/submissions: List submissions by status (?status=Pending|Approved|Published|Rejected)
- GET /api/community/admin/submissions/{submissionId}: Get submission details
- POST /api/community/admin/submissions/{submissionId}/approve: Approve submission (Pending → Approved)
- POST /api/community/admin/submissions/{submissionId}/publish: Publish to store, creates Printful product (Approved → Published)
- POST /api/community/admin/submissions/{submissionId}/unpublish: Remove from store, deletes Printful product (Published → Approved)
- POST /api/community/admin/submissions/{submissionId}/reject: Reject with reason (Pending → Rejected)

### Web Form

Humans can also submit via the web form: https://store.lightningenable.com/store/submit

## Links

- Store: https://store.lightningenable.com
- Full API Docs: https://store.lightningenable.com/llms-full.txt
- MCP Setup: https://store.lightningenable.com/skills.md
- Documentation: https://docs.lightningenable.com