# Lightning Enable Store — Full API Reference

> Part of [Lightning Enable](https://lightningenable.com) — infrastructure for agent commerce over Lightning.

> Complete API documentation for AI agents purchasing from the Lightning Enable Store.
> Base URL: https://store.lightningenable.com

## Table of Contents

- Catalog Endpoints (3)
- Cart Endpoints (6)
- Checkout and Fulfillment Endpoints (5)
- Complete Purchase Flow Example
- MCP Server Setup
- Community Collection (designs by community members; same purchase flow)

---

## Product ID Conventions

- **Ids 1–4** — Official Lightning Enable merchandise (t-shirts, snapback, dad hat). Always present.
- **Ids ≥ 1000** — Community Collection. Designer-submitted, admin-approved designs whose profits are donated to Bitcoin causes. When the designer specifies a beneficiary, it appears in the product's `description`; otherwise the description states profits go to Bitcoin causes generally. The list grows as designers publish. Discover them in `GET /api/store/catalog`.

Both ranges purchase through the **same** `/api/store/catalog`, `/api/store/products/{id}`, `/api/store/cart`, `/api/store/checkout`, and `/api/store/claim` endpoints with identical request/response shapes. Treat them the same way; no special handling required for community ids.

---

## Catalog Endpoints

### GET /api/store/catalog

List all products with real-time prices in satoshis and USD. Returns both official merchandise (ids 1–4) and any published Community Collection products (ids ≥ 1000) in a single `products` array.

**Request:**
```
GET /api/store/catalog
```

**Response (200):**
```json
{
  "products": [
    {
      "id": 1,
      "name": "Lightning Enable T-Shirt",
      "description": "Premium cotton t-shirt with Lightning Enable logo",
      "priceUsd": 30.00,
      "priceSats": 37311,
      "category": "Apparel",
      "sizes": ["S", "M", "L", "XL", "2XL", "3XL"],
      "colors": ["Black"],
      "inStock": true,
      "imageUrl": "https://files.cdn.printful.com/files/.../preview.png"
    },
    {
      "id": 1000,
      "name": "#FREESAMOURAI",
      "description": "Protest design supporting Samourai Wallet and developer freedom. Code is not a crime. ALL proceeds from this shirt go directly to imprisoned Samourai developers. — Designed by Mike Rahel.",
      "priceUsd": 30.00,
      "priceSats": 37311,
      "category": "Community T-Shirt",
      "sizes": ["S", "M", "L", "XL", "2XL", "3XL"],
      "colors": ["Black"],
      "inStock": true,
      "imageUrl": "https://files.cdn.printful.com/files/.../preview.png"
    }
  ],
  "btcUsdRate": 80303,
  "currency": "sats",
  "storeName": "Lightning Enable Store",
  "storeUrl": "https://store.lightningenable.com",
  "paymentMethod": "Lightning Network (L402)",
  "shippingRegions": ["US"],
  "supportEmail": "support@lightningenable.com",
  "purchaseFlow": { "...": "step-by-step instructions; applies to all product ids" }
}
```

Notes for agents:
- The `description` field for community products typically embeds a beneficiary statement (when the designer provided one) plus a "— Designed by …" attribution. When no beneficiary is specified, the description simply states that profits go to Bitcoin causes. Surface the description to your user before checkout if the cause matters.
- `category` distinguishes official products (`"Apparel"`) from community ones (`"Community T-Shirt"`, `"Community Snapback"`, `"Community Dad Hat"`).
- Community products are cached server-side for 5 minutes — newly published designs may take that long to appear.

### GET /api/store/products/{id}

Get a single product by ID with full details. Works for both official ids (1–4) and community ids (≥ 1000).

**Request:**
```
GET /api/store/products/1000
```

**Response (200):**
```json
{
  "id": 1000,
  "name": "#FREESAMOURAI",
  "description": "Protest design supporting Samourai Wallet and developer freedom. Code is not a crime. ALL proceeds from this shirt go directly to imprisoned Samourai developers. — Designed by Mike Rahel.",
  "priceUsd": 30.00,
  "priceSats": 37311,
  "category": "Community T-Shirt",
  "sizes": ["S", "M", "L", "XL", "2XL", "3XL"],
  "colors": ["Black"],
  "inStock": true,
  "imageUrl": "https://files.cdn.printful.com/files/.../preview.png"
}
```

**Response (404):**
```json
{
  "error": "Product not found",
  "productId": 999
}
```

### GET /api/store/health

Health check for the store API.

**Request:**
```
GET /api/store/health
```

**Response (200):**
```json
{
  "status": "healthy",
  "timestamp": "2026-02-08T12:00:00Z"
}
```

---

## Cart Endpoints

The cart is session-based. Cart state persists via cookies or session headers.

### GET /api/store/cart

Get current shopping cart contents with totals.

**Request:**
```
GET /api/store/cart
```

**Response (200):**
```json
{
  "items": [
    {
      "productId": 1,
      "name": "Lightning Enable T-Shirt",
      "size": "L",
      "color": "Black",
      "quantity": 1,
      "priceUsd": 25.00,
      "priceSats": 25000
    }
  ],
  "totalUsd": 25.00,
  "totalSats": 25000,
  "itemCount": 1,
  "btcUsdRate": 100000
}
```

### POST /api/store/cart/items

Add an item to the cart.

**Request:**
```
POST /api/store/cart/items
Content-Type: application/json

{
  "productId": 1,
  "quantity": 1,
  "size": "L",
  "color": "Black"
}
```

**Response (200):**
```json
{
  "success": true,
  "cart": {
    "items": [...],
    "totalUsd": 25.00,
    "totalSats": 25000,
    "itemCount": 1
  }
}
```

**Response (400):**
```json
{
  "error": "Invalid size. Available sizes: S, M, L, XL, 2XL"
}
```

### PUT /api/store/cart/items/{productId}

Update the quantity of an item already in the cart.

**Request:**
```
PUT /api/store/cart/items/1
Content-Type: application/json

{
  "quantity": 2
}
```

**Response (200):**
```json
{
  "success": true,
  "cart": {
    "items": [...],
    "totalUsd": 50.00,
    "totalSats": 50000,
    "itemCount": 2
  }
}
```

### DELETE /api/store/cart/items/{productId}

Remove an item from the cart. Use query parameters to target a specific size/color variant.

**Request:**
```
DELETE /api/store/cart/items/1?size=L&color=Black
```

**Response (200):**
```json
{
  "success": true,
  "cart": {
    "items": [],
    "totalUsd": 0,
    "totalSats": 0,
    "itemCount": 0
  }
}
```

### DELETE /api/store/cart

Clear all items from the cart.

**Request:**
```
DELETE /api/store/cart
```

**Response (200):**
```json
{
  "success": true,
  "cart": {
    "items": [],
    "totalUsd": 0,
    "totalSats": 0,
    "itemCount": 0
  }
}
```

### GET /api/store/cart/count

Get the current cart item count. Lightweight endpoint for UI badges.

**Request:**
```
GET /api/store/cart/count
```

**Response (200):**
```json
{
  "count": 1
}
```

---

## Checkout and Fulfillment Endpoints

### POST /api/store/checkout

Create a checkout session. Returns HTTP 402 (Payment Required) with a Lightning invoice and L402 macaroon.

You can either checkout from the cart or provide items directly in the request body.

**Request (direct items):**
```
POST /api/store/checkout
Content-Type: application/json

{
  "items": [
    {
      "productId": 1,
      "quantity": 1,
      "size": "L",
      "color": "Black"
    }
  ]
}
```

**Request (from cart — empty body or omit items):**
```
POST /api/store/checkout
Content-Type: application/json

{}
```

**Response (402 Payment Required):**
```json
{
  "invoice": "lnbc250000n1pj...",
  "macaroon": "AgELbGlnaHRuaW5n...",
  "paymentHash": "a1b2c3d4e5f6...",
  "amountSats": 25000,
  "amountUsd": 25.00,
  "expiresAt": "2026-02-08T12:10:00Z",
  "items": [
    {
      "productId": 1,
      "name": "Lightning Enable T-Shirt",
      "size": "L",
      "color": "Black",
      "quantity": 1,
      "priceSats": 25000
    }
  ]
}
```

**Response (400):**
```json
{
  "error": "Cart is empty"
}
```

### POST /api/store/claim

Claim a paid order using your L402 credential (macaroon + preimage). Returns a claim token and URL for the human to enter shipping details.

**Request:**
```
POST /api/store/claim
Authorization: L402 {macaroon}:{preimage}
Content-Type: application/json

{
  "l402Credential": "{macaroon}:{preimage}"
}
```

**Response (200):**
```json
{
  "success": true,
  "claimToken": "ct_abc123def456",
  "claimUrl": "https://store.lightningenable.com/claim/ct_abc123def456",
  "message": "Order claimed! Share the claim URL with the buyer to enter shipping details.",
  "expiresAt": "2026-02-09T12:00:00Z"
}
```

**Response (401):**
```json
{
  "error": "Invalid L402 credential. Verify SHA256(preimage) matches the payment hash."
}
```

**Response (409):**
```json
{
  "error": "Order already claimed"
}
```

### GET /api/store/payment-status/{paymentHash}

Poll payment status by payment hash. Use this for frontends or agents that need to wait for payment confirmation.

**Request:**
```
GET /api/store/payment-status/a1b2c3d4e5f6...
```

**Response (200 — pending):**
```json
{
  "paymentHash": "a1b2c3d4e5f6...",
  "status": "pending",
  "amountSats": 25000,
  "createdAt": "2026-02-08T12:00:00Z"
}
```

**Response (200 — paid):**
```json
{
  "paymentHash": "a1b2c3d4e5f6...",
  "status": "paid",
  "amountSats": 25000,
  "paidAt": "2026-02-08T12:01:30Z"
}
```

### GET /api/store/order/{claimToken}

Get order status by claim token. Use after claiming to check fulfillment progress.

**Request:**
```
GET /api/store/order/ct_abc123def456
```

**Response (200):**
```json
{
  "claimToken": "ct_abc123def456",
  "status": "awaiting_shipping",
  "items": [
    {
      "productId": 1,
      "name": "Lightning Enable T-Shirt",
      "size": "L",
      "color": "Black",
      "quantity": 1
    }
  ],
  "amountSats": 25000,
  "paidAt": "2026-02-08T12:01:30Z",
  "shippingSubmitted": false
}
```

### POST /api/store/order/{claimToken}/fulfill

Submit shipping details to fulfill the order. This triggers Printful to begin production and shipping.

**Request:**
```
POST /api/store/order/ct_abc123def456/fulfill
Content-Type: application/json

{
  "name": "John Doe",
  "address1": "123 Main St",
  "address2": "Apt 4B",
  "city": "Austin",
  "stateCode": "TX",
  "zip": "78701",
  "countryCode": "US",
  "email": "john@example.com"
}
```

**Response (200):**
```json
{
  "success": true,
  "message": "Order submitted to Printful for fulfillment",
  "estimatedDelivery": "5-10 business days"
}
```

**Response (400):**
```json
{
  "error": "Shipping address is required"
}
```

---

## Complete Purchase Flow Example

Here is the full end-to-end flow an AI agent follows to purchase from the store:

### Step 1: Browse the catalog
```
GET /api/store/catalog
```
Response includes all products with IDs, prices in sats, available sizes and colors.

### Step 2: Add item to cart (optional — can also checkout directly)
```
POST /api/store/cart/items
Content-Type: application/json

{"productId": 1, "quantity": 1, "size": "L", "color": "Black"}
```

### Step 3: Checkout
```
POST /api/store/checkout
Content-Type: application/json

{"items": [{"productId": 1, "quantity": 1, "size": "L", "color": "Black"}]}
```
Response: HTTP 402 with `invoice` (BOLT11), `macaroon`, `paymentHash`, `amountSats`.

### Step 4: Pay the Lightning invoice
Pay the BOLT11 invoice string from the checkout response using any Lightning wallet.
You will receive a `preimage` (64-character hex string) as proof of payment.

If using the Lightning Enable MCP server:
```
Tool: pay_invoice
Input: {"invoice": "lnbc250000n1pj..."}
Output: {"preimage": "abc123...", "amountSats": 25000}
```

### Step 5: Claim the order
```
POST /api/store/claim
Authorization: L402 {macaroon}:{preimage}
Content-Type: application/json

{"l402Credential": "{macaroon}:{preimage}"}
```
Response: `claimToken` and `claimUrl`.

### Step 6: Human enters shipping
Share the `claimUrl` with the human buyer. They visit the URL, enter their shipping address, and the order is sent to Printful for fulfillment.

### Step 7: Check order status (optional)
```
GET /api/store/order/{claimToken}
```

---

## MCP Server Setup

To give your AI agent Lightning payment and API discovery capabilities, install the Lightning Enable MCP server:

```bash
dotnet tool install --global LightningEnable.Mcp
```
Or via Python: `pip install lightning-enable-mcp`

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

### Claude Desktop Configuration

Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "lightning-enable": {
      "command": "lightning-enable-mcp",
      "env": {
        "NWC_CONNECTION_STRING": "nostr+walletconnect://..."
      }
    }
  }
}
```

### Supported Wallets

| Wallet | Environment Variable | Notes |
|--------|---------------------|-------|
| Alby Hub (NWC) | `NWC_CONNECTION_STRING` | Recommended. Returns preimage for L402. |
| Strike | `STRIKE_API_KEY` | Returns preimage. BTC balance used. |
| OpenNode | `OPENNODE_API_KEY` | Does NOT return preimage. Not compatible with L402 store purchases. |

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `check_wallet_balance` | Check your Lightning wallet balance |
| `pay_invoice` | Pay a BOLT11 Lightning invoice |
| `discover_api` | Search the L402 API registry or fetch a specific API's manifest |
| `access_l402_resource` | Auto-pay L402-protected APIs |
| `pay_l402_challenge` | Manually pay an L402 challenge |
| `get_payment_history` | View recent payments |
| `get_budget_status` | Check spending limits |

### Budget Controls

| Setting | Default | Environment Variable |
|---------|---------|---------------------|
| Per-request limit | 1,000 sats | `L402_MAX_SATS_PER_REQUEST` |
| Per-session limit | 10,000 sats | `L402_MAX_SATS_PER_SESSION` |

For store purchases (typically 30,000-40,000 sats), increase the per-request limit:
```bash
export L402_MAX_SATS_PER_REQUEST=50000
export L402_MAX_SATS_PER_SESSION=100000
```

---

## Error Handling

All errors return JSON with an `error` field:

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

### Common Error Responses

```json
{"error": "Cart is empty"}
{"error": "Invalid size. Available sizes: S, M, L, XL, 2XL"}
{"error": "Invalid L402 credential. Verify SHA256(preimage) matches the payment hash."}
{"error": "Order already claimed"}
{"error": "Product not found"}
```

## Rate Limits

| Endpoint | Limit |
|----------|-------|
| POST /api/store/checkout | 10 requests per minute |
| Cart operations (/api/store/cart/*) | 30 requests per minute |
| Catalog endpoints | No limit (cached) |
| Community submission | 5 requests per minute |

When rate limited, wait 60 seconds before retrying.

## Important Notes

- All prices are dynamic and fetched from Printful in real-time
- Prices are displayed in satoshis at checkout; USD shown for reference
- Lightning invoices expire in 10 minutes — complete the flow promptly
- Shipping is US only
- All sales are final (no refunds)
- The preimage MUST match the invoice: `SHA256(preimage) == paymentHash`

---

## Community Collection

Two distinct flows live under "Community Collection":

1. **Buying a community design** — Use the regular store endpoints. Community products appear in `GET /api/store/catalog` with ids ≥ 1000 and purchase identically to official merchandise via `POST /api/store/checkout`. **No special endpoints to learn.** Skip ahead to the Design Submission API below only if you're an agent that wants to submit a new design rather than buy an existing one.
2. **Submitting a new design** — L402-style flow described below: pay a 2,000 sat fee via Lightning, upload a PNG, await admin review and publication.

100% of profits from sold community designs are donated to Bitcoin causes (open-source development funds, defense funds, education, and other initiatives that strengthen the ecosystem). When a designer specifies a beneficiary, it appears in the product's `description`; otherwise the description states profits go to Bitcoin causes generally. Surface the description to your user before purchase if relevance to a particular cause matters.

### Buying a community design (id ≥ 1000)

```
# 1. Discover
GET /api/store/catalog
# look for products where id >= 1000

# 2. Inspect (optional)
GET /api/store/products/1000

# 3. Checkout — same shape as official merchandise
POST /api/store/checkout
Content-Type: application/json
{ "items": [{ "productId": 1000, "quantity": 1, "size": "M", "color": "Black" }] }
# Returns HTTP 402 with { invoice, macaroon, paymentHash, amountSats, ... }

# 4. Pay BOLT11 invoice via Lightning wallet → receive preimage

# 5. Claim
POST /api/store/claim
Authorization: L402 {macaroon}:{preimage}
{ "l402Credential": "{macaroon}:{preimage}" }
# Returns claimUrl for human to enter shipping
```

### Design Submission API (separate flow — only for designers submitting new work)

This is an L402-style flow: pay a 2,000 sat fee via Lightning to submit your design for admin review.

### GET /api/community/submit/info

Get submission requirements and current pricing.

**Request:**
```
GET /api/community/submit/info
```

**Response (200):**
```json
{
  "submissionFeeSats": 2000,
  "submissionFeeUsd": 3.54,
  "acceptedFileTypes": [".png"],
  "maxFileSizeMb": 50,
  "minDimensions": { "width": 2400, "height": 2400 },
  "productTypes": [
    { "type": "TShirt", "name": "T-Shirt", "price": 25.00 },
    { "type": "Snapback", "name": "Snapback", "price": 28.00 },
    { "type": "DadHat", "name": "Dad Hat", "price": 24.00 }
  ]
}
```

### POST /api/community/submit/initiate

Initiate a submission and receive a Lightning invoice for the submission fee.

**Request:**
```
POST /api/community/submit/initiate
Content-Type: application/x-www-form-urlencoded

DesignerName=John+Doe&DesignerEmail=john@example.com&DesignName=My+Bitcoin+Art&ProductType=TShirt&DesignDescription=A+cool+design
```

**Required Fields:**
- `DesignerName`: Your name (displayed with the design)
- `DesignerEmail`: Email for notifications
- `DesignName`: Name of your design
- `ProductType`: One of `TShirt`, `Snapback`, `DadHat`

**Optional Fields:**
- `DesignerHandle`: Social handle (e.g., your Twitter/X username)
- `TwitterUrl`: Link to your Twitter/X profile
- `NostrPubkey`: Your Nostr public key
- `DesignDescription`: Description of the design

**Response (200):**
```json
{
  "paymentHash": "ae50f115f58ffc9286cbf6ecb4ad697c",
  "invoice": "lnbc50010n1p5cjyqr...",
  "checkoutUrl": "https://store.lightningenable.com/checkout/lightning/inv_abc123",
  "amountSats": 2000,
  "expiresIn": 600
}
```

**Payment Options:**
- **Agents:** Pay the BOLT11 `invoice` directly using the `pay_invoice` MCP tool or any Lightning wallet. No human required.
- **Human-assisted:** Share the `checkoutUrl` with a human if the agent lacks a Lightning wallet — opens the hosted checkout page where Lightning is the default payment method.

### GET /api/community/submit/status/{paymentHash}

Check if the Lightning payment has been confirmed.

**Request:**
```
GET /api/community/submit/status/ae50f115f58ffc9286cbf6ecb4ad697c
```

**Response (200 — pending):**
```json
{
  "paid": false,
  "paymentHash": "ae50f115f58ffc9286cbf6ecb4ad697c"
}
```

**Response (200 — paid):**
```json
{
  "paid": true,
  "paymentHash": "ae50f115f58ffc9286cbf6ecb4ad697c"
}
```

### POST /api/community/submit/complete

Complete the submission after payment is confirmed. Upload your design file.

**Request:**
```
POST /api/community/submit/complete
Content-Type: multipart/form-data

PaymentHash=ae50f115f58ffc9286cbf6ecb4ad697c
DesignFile=[your-design.png]
```

**Response (200):**
```json
{
  "success": true,
  "submissionId": "sub_abc123",
  "message": "Design submitted successfully! We'll review it and get back to you."
}
```

**Response (400 — payment not confirmed):**
```json
{
  "error": "Payment not confirmed"
}
```

### GET /api/community/submissions/{submissionId}

Check the review status of your submission.

**Request:**
```
GET /api/community/submissions/sub_abc123
```

**Response (200):**
```json
{
  "submissionId": "sub_abc123",
  "designName": "My Bitcoin Art",
  "status": "Pending",
  "submittedAt": "2026-02-08T12:00:00Z",
  "reviewedAt": null,
  "rejectionReason": null
}
```

**Status Values:**
- `Pending`: Awaiting review
- `Approved`: Approved, awaiting publication
- `Published`: Live in the store
- `Rejected`: Not accepted (see `rejectionReason`)

---

## Complete Submission Flow Example

Here is the full end-to-end flow for an AI agent to submit a design:

### Step 1: Get requirements
```
GET /api/community/submit/info
```
Response shows 2,000 sats fee, accepted file types (PNG only), and product types.

### Step 2: Initiate submission
```
POST /api/community/submit/initiate
Content-Type: application/x-www-form-urlencoded

DesignerName=AI+Artist&DesignerEmail=ai@example.com&DesignName=Lightning+Bolt+Design&ProductType=TShirt
```
Response: `invoice` (BOLT11), `checkoutUrl` (hosted payment page), and `paymentHash`.

### Step 3: Pay the submission fee (2,000 sats)
**For Agents:** Pay the BOLT11 `invoice` directly using the `pay_invoice` MCP tool. No human required.

**Human-assisted:** If the agent lacks a Lightning wallet, share the `checkoutUrl` with a human to pay via the hosted checkout page.

### Step 4: Poll for payment confirmation
```
GET /api/community/submit/status/{paymentHash}
```
Repeat until `paid: true`.

### Step 5: Upload design file
```
POST /api/community/submit/complete
Content-Type: multipart/form-data

PaymentHash={paymentHash}
DesignFile=[design.png]
```
Response: `submissionId` for tracking.

### Step 6: Check submission status
```
GET /api/community/submissions/{submissionId}
```
Monitor status: Pending → Approved → Published.

---

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

These endpoints are for store administrators to manage community submissions.

### GET /api/community/admin/submissions

List submissions filtered by status.

**Request:**
```
GET /api/community/admin/submissions?status=Pending
X-Store-Admin-Key: your-admin-key
```

**Status Values:** `Pending`, `Approved`, `Published`, `Rejected`

### POST /api/community/admin/submissions/{submissionId}/approve

Approve a pending submission.

**Request:**
```
POST /api/community/admin/submissions/sub_abc123/approve
X-Store-Admin-Key: your-admin-key
```

### POST /api/community/admin/submissions/{submissionId}/publish

Publish an approved submission to the store. Automatically creates the Printful sync product.

**Request:**
```
POST /api/community/admin/submissions/sub_abc123/publish
X-Store-Admin-Key: your-admin-key
```

### POST /api/community/admin/submissions/{submissionId}/unpublish

Remove a published submission from the store. Deletes the Printful sync product and moves the submission back to Approved status.

**Request:**
```
POST /api/community/admin/submissions/sub_abc123/unpublish
X-Store-Admin-Key: your-admin-key
```

### POST /api/community/admin/submissions/{submissionId}/reject

Reject a pending submission with a reason.

**Request:**
```
POST /api/community/admin/submissions/sub_abc123/reject
X-Store-Admin-Key: your-admin-key
Content-Type: application/json

{
  "reason": "Design does not meet quality standards"
}
```

---

## Links

- Store: https://store.lightningenable.com
- Summary: https://store.lightningenable.com/llms.txt
- MCP Setup: https://store.lightningenable.com/skills.md
- Documentation: https://docs.lightningenable.com
- Support: support@lightningenable.com