# 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

---

## Catalog Endpoints

### GET /api/store/catalog

List all products with real-time prices in satoshis and USD.

**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": 25.00,
      "priceSats": 25000,
      "sizes": ["S", "M", "L", "XL", "2XL"],
      "colors": ["Black"],
      "inStock": true,
      "imageUrl": "/images/store/lightning-enable-tshirt.png"
    }
  ],
  "btcUsdRate": 100000,
  "currency": "sats",
  "storeName": "Lightning Enable Store",
  "paymentMethod": "Lightning Network (L402)",
  "shippingRegions": ["US"]
}
```

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

Get a single product by ID with full details.

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

**Response (200):**
```json
{
  "id": 1,
  "name": "Lightning Enable T-Shirt",
  "description": "Premium cotton t-shirt with Lightning Enable logo",
  "priceUsd": 25.00,
  "priceSats": 25000,
  "sizes": ["S", "M", "L", "XL", "2XL"],
  "colors": ["Black"],
  "inStock": true,
  "imageUrl": "/images/store/lightning-enable-tshirt.png"
}
```

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

### 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 — Design Submission API

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.

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

### 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