# WalletWallet API

> Generate Apple Wallet passes with a single API call. No Apple Developer account or certificate setup required.

## Base URL

https://api.walletwallet.dev

## Authentication

All requests require a Bearer token in the Authorization header:

    Authorization: Bearer ww_live_<your_key>

Get an API key at: https://walletwallet.dev/signup/

## Endpoints

### POST /api/pkpass

Generate an Apple Wallet pass (.pkpass file).

Request headers:
- Content-Type: application/json
- Authorization: Bearer ww_live_<your_key>

Request body (JSON):

| Field           | Type   | Required | Description                                                        |
|-----------------|--------|----------|--------------------------------------------------------------------|
| barcodeValue    | string | Yes      | Data encoded in the barcode (e.g. member ID, ticket number)        |
| barcodeFormat   | string | Yes      | One of: QR, PDF417, Aztec, Code128                                 |
| title           | string | Yes      | Pass title displayed on the card                                   |
| label           | string | No       | Label text above the value field                                   |
| value           | string | No       | Value text displayed below the label                               |
| colorPreset     | string | No       | Color theme: blue, green, red, purple, orange, dark                |
| color           | string | No       | Custom hex color, e.g. "#1e40af" (Pro plan only)                   |
| logoURL         | string | No       | URL to custom logo image, HTTPS or PNG data URI (Pro plan only)    |
| expirationDays  | number | No       | Pass expires after 30, 90, or 365 days                             |

Response:
- 200: Returns application/vnd.apple.pkpass binary file
- 400: Invalid request body or missing required fields
- 401: Invalid or missing API key
- 429: Rate limit exceeded
- 500: Server error

Error responses return JSON:

    {"error": "Error message describing the issue"}

### GET /api/auth/usage

Get current month's usage stats for the authenticated API key.

Request headers:
- Authorization: Bearer ww_live_<your_key>

Response (200, JSON):

    {
      "count": 42,
      "limit": 100000,
      "remaining": 99958,
      "resetDate": "2026-03-01",
      "plan": "pro"
    }

## Plans and Rate Limits

| Plan | Monthly Limit | Custom Colors | Custom Logo | Price    |
|------|---------------|---------------|-------------|----------|
| Free | 1,000         | No            | No          | $0/month |
| Pro  | 100,000       | Yes           | Yes         | $19/month|

Rate limits reset on the 1st of each month (UTC).

## Barcode Formats

| Format  | Best For                          |
|---------|-----------------------------------|
| QR      | General purpose, high data capacity |
| PDF417  | Boarding passes, IDs              |
| Aztec   | Transit tickets, compact spaces   |
| Code128 | Retail, inventory                 |

## Examples

### cURL — Basic Pass

    curl -X POST https://api.walletwallet.dev/api/pkpass \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ww_live_<your_key>" \
      -d '{
        "barcodeValue": "MEMBER-12345",
        "barcodeFormat": "QR",
        "title": "Membership Card"
      }' \
      -o membership.pkpass

### cURL — Full Options

    curl -X POST https://api.walletwallet.dev/api/pkpass \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ww_live_<your_key>" \
      -d '{
        "barcodeValue": "LOYALTY-98765",
        "barcodeFormat": "QR",
        "title": "Coffee Rewards",
        "label": "Member",
        "value": "Gold Status",
        "colorPreset": "dark",
        "expirationDays": 365
      }' \
      -o rewards.pkpass

### cURL — Pro Plan Custom Branding

    curl -X POST https://api.walletwallet.dev/api/pkpass \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ww_live_<your_key>" \
      -d '{
        "barcodeValue": "VIP-001",
        "barcodeFormat": "QR",
        "title": "VIP Access",
        "color": "#8B4513",
        "logoURL": "https://example.com/logo.png"
      }' \
      -o vip.pkpass

### JavaScript / Node.js

    const response = await fetch('https://api.walletwallet.dev/api/pkpass', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ww_live_<your_key>'
      },
      body: JSON.stringify({
        barcodeValue: 'TICKET-789',
        barcodeFormat: 'QR',
        title: 'Event Ticket',
        label: 'Seat',
        value: 'A-23'
      })
    });

    const blob = await response.blob();
    // Save or send to user

### Python

    import requests

    response = requests.post(
        'https://api.walletwallet.dev/api/pkpass',
        headers={
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ww_live_<your_key>'
        },
        json={
            'barcodeValue': 'ORDER-456',
            'barcodeFormat': 'Code128',
            'title': 'Order Pickup',
            'label': 'Order #',
            'value': '456'
        }
    )

    with open('order.pkpass', 'wb') as f:
        f.write(response.content)

## Testing Your Pass

1. Save the response to a .pkpass file
2. On macOS: double-click to preview in Finder
3. On iOS: AirDrop or email the file to your device
4. The pass will prompt to add to Apple Wallet

## Support

Email: alen@walletwallet.dev
Docs: https://walletwallet.dev