opencard 1.0.0

package/API.md

@@ -0,0 +1,564 @@
+# OpenCard API Documentation
+
+**Base URL**: `http://localhost:3000` (development) | `https://your-domain.com` (production)
+
+---
+
+## Authentication
+
+OpenCard uses two authentication modes:
+
+### 1. x402 Payment (Paid Endpoints)
+
+This flow is designed for **AI agents** to autonomously pay for services.
+
+1.  **Agent Request**: `POST /cards/create/tier/10` (no payment)
+2.  **Server Response**: `402 Payment Required`
+    ```json
+    {
+      "x402Version": 1,
+      "accepts": [
+        {
+          "scheme": "exact",
+          "network": "eip155:8453", // Base Mainnet
+          "asset": "0x8335...2913", // USDC Contract
+          "maxAmountRequired": "17200000", // 17.20 USDC (6 decimals)
+          "payTo": "0x3Be8...c288" // Treasury Address
+        }
+      ]
+    }
+    ```
+3.  **Agent Action**: Parse `accepts`, send 17.20 USDC to `payTo` on Base.
+4.  **Agent Retry**: Resend request with `X-Payment` header:
+    ```json
+    // Header value is base64-encoded JSON:
+    {
+      "scheme": "exact",
+      "network": "eip155:8453",
+      "payload": {
+        "authorization": {
+          "from": "0xAgentAddress",
+          "to": "0xTreasuryAddress",
+          "value": "17200000"
+        },
+        "txHash": "0xTxHash..."
+      }
+    }
+    ```
+
+### 2. Wallet Signature (Free Endpoints)
+
+Sign an EIP-712 typed message and include these headers:
+
+| Header               | Description                               |
+| -------------------- | ----------------------------------------- |
+| `X-WALLET-ADDRESS`   | Your `0x...` wallet address               |
+| `X-WALLET-SIGNATURE` | EIP-712 signature                         |
+| `X-WALLET-TIMESTAMP` | Unix timestamp (must be within 5 minutes) |
+
+**EIP-712 Domain:**
+
+```json
+{
+  "name": "OpenCard",
+  "version": "1",
+  "chainId": 8453
+}
+```
+
+**EIP-712 Types:**
+
+```json
+{
+  "Auth": [
+    { "name": "action", "type": "string" },
+    { "name": "timestamp", "type": "uint256" }
+  ]
+}
+```
+
+**Message:**
+
+```json
+{
+  "action": "opencard-auth",
+  "timestamp": 1707600000
+}
+```
+
+---
+
+## Public Endpoints
+
+### `GET /health`
+
+Health check.
+
+**Response** `200`:
+
+```json
+{
+  "status": "ok",
+  "timestamp": "2026-02-11T14:00:00.000Z",
+  "version": "1.0.0"
+}
+```
+
+---
+
+### `GET /pricing`
+
+Returns full pricing breakdown for all tiers.
+
+**Response** `200`:
+
+```json
+{
+  "creation": {
+    "tiers": [
+      {
+        "loadAmount": 10,
+        "totalCost": 17.2,
+        "issuanceFee": 3.0,
+        "topUpFee": 2.2,
+        "ourFee": 2.0,
+        "endpoint": "/cards/create/tier/10"
+      }
+    ]
+  },
+  "funding": {
+    "tiers": [
+      {
+        "fundAmount": 10,
+        "totalCost": 14.2,
+        "topUpFee": 2.2,
+        "ourFee": 2.0,
+        "endpoint": "/cards/fund/tier/10"
+      }
+    ]
+  }
+}
+```
+
+---
+
+### `GET /cards/tiers`
+
+Returns available tiers with endpoints and fee breakdowns.
+
+**Response** `200`:
+
+```json
+{
+  "creation": [
+    {
+      "loadAmount": 10,
+      "totalCost": 17.2,
+      "endpoint": "/cards/create/tier/10",
+      "breakdown": {
+        "cardLoad": 10,
+        "issuanceFee": 3,
+        "topUpFee": 2.2,
+        "ourFee": 2,
+        "buffer": 0
+      }
+    }
+  ],
+  "funding": [
+    {
+      "fundAmount": 10,
+      "totalCost": 14.2,
+      "endpoint": "/cards/fund/tier/10",
+      "breakdown": {
+        "fundAmount": 10,
+        "topUpFee": 2.2,
+        "ourFee": 2
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Paid Endpoints (x402)
+
+These endpoints require USDC payment via the x402 protocol on Base.
+
+### `POST /cards/create/tier/:amount`
+
+Create a new virtual card loaded with the specified tier amount.
+
+**Available tiers**: `10`, `25`, `50`, `100`, `200`, `500`
+
+**Request Body:**
+
+```json
+{
+  "nameOnCard": "JOHN DOE",
+  "email": "john@example.com"
+}
+```
+
+**402 Response** (when no payment provided):
+
+```json
+{
+  "x402Version": 1,
+  "accepts": [
+    {
+      "scheme": "exact",
+      "network": "eip155:8453",
+      "maxAmountRequired": "17200000",
+      "resource": "/cards/create/tier/10",
+      "description": "Create card with $10 load",
+      "payTo": "0x3Be892b244B7CE6731A297A7eBca16F16f27c288",
+      "maxTimeoutSeconds": 300,
+      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+    }
+  ]
+}
+```
+
+**Success Response** `201`:
+
+```json
+{
+  "success": true,
+  "card": {
+    "cardId": "uuid",
+    "kripiCardId": "kc_123",
+    "nameOnCard": "JOHN DOE",
+    "balance": 10,
+    "status": "active",
+    "createdAt": "2026-02-11T14:00:00.000Z"
+  },
+  "payment": {
+    "amountCharged": 17.2,
+    "txHash": "0x...",
+    "network": "base"
+  },
+  "details": {
+    "cardNumber": "4111111111111111",
+    "expiryMonth": 12,
+    "expiryYear": 2028,
+    "cvv": "123",
+    "billingAddress": {
+      "street": "123 Main St",
+      "city": "San Francisco",
+      "state": "CA",
+      "zip": "94105",
+      "country": "US"
+    }
+  }
+}
+```
+
+---
+
+### `POST /cards/fund/tier/:amount`
+
+Add funds to an existing card.
+
+**Available tiers**: `10`, `25`, `50`, `100`, `200`, `500`
+
+**Request Body:**
+
+```json
+{
+  "cardId": "uuid-of-existing-card"
+}
+```
+
+**Success Response** `200`:
+
+```json
+{
+  "success": true,
+  "cardId": "uuid",
+  "kripiCardId": "kc_123",
+  "fundedAmount": 25,
+  "newBalance": 35.0,
+  "payment": {
+    "amountCharged": 29.4,
+    "txHash": "0x...",
+    "network": "base"
+  }
+}
+```
+
+---
+
+## Wallet-Signed Endpoints
+
+All require [wallet signature auth headers](#2-wallet-signature-free-endpoints).
+
+### `GET /cards`
+
+List all cards owned by the authenticated wallet.
+
+**Response** `200`:
+
+```json
+{
+  "cards": [
+    {
+      "cardId": "uuid",
+      "kripiCardId": "kc_123",
+      "nameOnCard": "JOHN DOE",
+      "lastFour": "****",
+      "balance": 10.0,
+      "status": "active",
+      "createdAt": "2026-02-11T14:00:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+### `GET /cards/:cardId`
+
+Get detailed card info (fetches live balance from KripiCard).
+
+**Response** `200`:
+
+```json
+{
+  "card": {
+    "cardId": "uuid",
+    "kripiCardId": "kc_123",
+    "nameOnCard": "JOHN DOE",
+    "email": "john@example.com",
+    "balance": 8.5,
+    "initialAmountUsd": 10,
+    "status": "active",
+    "createdAt": "2026-02-11T14:00:00.000Z",
+    "updatedAt": "2026-02-11T15:30:00.000Z"
+  }
+}
+```
+
+---
+
+### `GET /cards/:cardId/details`
+
+Get sensitive card details (number, CVV, expiry). **Rate limited: 3 requests per card per hour.**
+
+**Response** `200`:
+
+```json
+{
+  "details": {
+    "cardNumber": "4111111111111111",
+    "expiryMonth": 12,
+    "expiryYear": 2028,
+    "cvv": "123",
+    "billingAddress": {
+      "street": "123 Main St",
+      "city": "San Francisco",
+      "state": "CA",
+      "zip": "94105",
+      "country": "US"
+    }
+  }
+}
+```
+
+---
+
+### `POST /cards/:cardId/freeze`
+
+Freeze a card (blocks all transactions).
+
+**Response** `200`:
+
+```json
+{
+  "success": true,
+  "cardId": "uuid",
+  "status": "frozen"
+}
+```
+
+---
+
+### `POST /cards/:cardId/unfreeze`
+
+Unfreeze a previously frozen card.
+
+**Response** `200`:
+
+```json
+{
+  "success": true,
+  "cardId": "uuid",
+  "status": "active"
+}
+```
+
+---
+
+## Admin Endpoints
+
+All require `Authorization: Bearer <ADMIN_SECRET>` header.
+
+### `GET /admin/api/stats`
+
+System-wide statistics.
+
+**Response** `200`:
+
+```json
+{
+  "cards": {
+    "totalCards": 15,
+    "activeCards": 12,
+    "frozenCards": 3
+  },
+  "transactions": {
+    "totalTransactions": 22,
+    "completedTransactions": 18,
+    "failedTransactions": 2,
+    "pendingTransactions": 2,
+    "totalRevenue": "156.00",
+    "totalVolume": "1250.00"
+  },
+  "wallets": {
+    "totalWallets": 8
+  }
+}
+```
+
+---
+
+### `GET /admin/api/transactions`
+
+List transactions with optional filtering.
+
+**Query Parameters:**
+
+| Param    | Type   | Default | Description                              |
+| -------- | ------ | ------- | ---------------------------------------- |
+| `status` | string | —       | Filter: `completed`, `failed`, `pending` |
+| `limit`  | number | 50      | Max results (capped at 100)              |
+| `offset` | number | 0       | Pagination offset                        |
+
+**Response** `200`:
+
+```json
+{
+  "transactions": [
+    {
+      "id": "uuid",
+      "walletAddress": "0x...",
+      "cardId": "uuid",
+      "type": "card_creation",
+      "amountUsd": "17.20",
+      "cardAmountUsd": "10.00",
+      "feeUsd": "2.00",
+      "kripiCardFeeUsd": "5.20",
+      "txHash": "0x...",
+      "status": "completed",
+      "errorMessage": null,
+      "createdAt": "2026-02-11T14:00:00.000Z"
+    }
+  ],
+  "limit": 50,
+  "offset": 0
+}
+```
+
+---
+
+### `GET /admin/api/cards`
+
+List all cards with optional wallet filter.
+
+**Query Parameters:**
+
+| Param    | Type   | Default | Description                 |
+| -------- | ------ | ------- | --------------------------- |
+| `wallet` | string | —       | Filter by wallet address    |
+| `limit`  | number | 50      | Max results (capped at 100) |
+| `offset` | number | 0       | Pagination offset           |
+
+---
+
+### `GET /admin/api/wallets`
+
+List all registered wallets (up to 100).
+
+**Response** `200`:
+
+```json
+{
+  "wallets": [
+    {
+      "id": "uuid",
+      "address": "0x...",
+      "firstSeenAt": "2026-02-11T14:00:00.000Z",
+      "totalSpentUsd": "154.20",
+      "cardCount": 3
+    }
+  ]
+}
+```
+
+---
+
+## Error Responses
+
+All errors follow the format:
+
+```json
+{
+  "error": "Human-readable error message"
+}
+```
+
+| Status | Meaning                                    |
+| ------ | ------------------------------------------ |
+| `400`  | Invalid request body or parameters         |
+| `401`  | Missing or invalid authentication          |
+| `402`  | Payment required (x402 flow)               |
+| `404`  | Card not found or doesn't belong to wallet |
+| `429`  | Rate limit exceeded                        |
+| `500`  | Internal server error                      |
+
+---
+
+## Rate Limits
+
+| Scope           | Limit                        |
+| --------------- | ---------------------------- |
+| General API     | 100 requests / 15 min per IP |
+| Paid endpoints  | 10 requests / 5 min per IP   |
+| Card details    | 3 requests / hour per card   |
+| Admin endpoints | 30 requests / 15 min per IP  |
+
+---
+
+## Pricing Tiers
+
+### Card Creation
+
+| Load | Issuance Fee | Top-Up Fee | Our Fee | **Total**   |
+| ---- | ------------ | ---------- | ------- | ----------- |
+| $10  | $3.00        | $2.20      | $2.00   | **$17.20**  |
+| $25  | $3.00        | $2.50      | $2.00   | **$32.50**  |
+| $50  | $3.00        | $3.00      | $2.00   | **$58.00**  |
+| $100 | $3.00        | $4.00      | $3.00   | **$110.00** |
+| $200 | $3.00        | $6.00      | $5.00   | **$214.00** |
+| $500 | $3.00        | $12.00     | $7.00   | **$522.00** |
+
+### Card Funding
+
+| Amount | Top-Up Fee | Our Fee | **Total**   |
+| ------ | ---------- | ------- | ----------- |
+| $10    | $2.20      | $2.00   | **$14.20**  |
+| $25    | $2.50      | $2.00   | **$29.50**  |
+| $50    | $3.00      | $2.00   | **$55.00**  |
+| $100   | $4.00      | $3.00   | **$107.00** |
+| $200   | $6.00      | $5.00   | **$211.00** |
+| $500   | $12.00     | $7.00   | **$519.00** |

package/DATABASE.md

@@ -0,0 +1,143 @@
+# OpenCard — Neon Database Setup
+
+## 1. Create a Neon Project
+
+1. Go to [https://neon.tech](https://neon.tech) and sign up / log in
+2. Click **"New Project"**
+3. Configure:
+   - **Project name**: `opencard`
+   - **Postgres version**: 16 (latest)
+   - **Region**: Pick closest to your server (e.g. `us-east-2` for US)
+   - **Compute size**: Free tier (0.25 CU) is fine for MVP
+4. Click **"Create Project"**
+
+## 2. Get Your Connection String
+
+After project creation, Neon shows your connection details. Copy the **connection string**:
+
+```
+postgresql://neondb_owner:YOUR_PASSWORD@ep-XXXXX.us-east-2.aws.neon.tech/neondb?sslmode=require
+```
+
+> [!IMPORTANT]
+> Save this immediately — the password is only shown once. You can reset it later from the Neon dashboard under **Connection Details**.
+
+## 3. Configure OpenCard
+
+Add the connection string to your `.env` file:
+
+```env
+DATABASE_URL=postgresql://neondb_owner:YOUR_PASSWORD@ep-XXXXX.us-east-2.aws.neon.tech/neondb?sslmode=require
+```
+
+## 4. Push the Schema
+
+From the OpenCard project root, run:
+
+```bash
+npm run db:push
+```
+
+This uses Drizzle Kit to push the schema directly to Neon. It creates 3 tables:
+
+| Table          | Purpose                                |
+| -------------- | -------------------------------------- |
+| `wallets`      | Agent wallet addresses, spend tracking |
+| `cards`        | Virtual cards linked to wallets        |
+| `transactions` | Payment & card operation history       |
+
+### Expected Output
+
+```
+[✓] Changes applied to database
+  - Created table "wallets"
+  - Created table "cards"
+  - Created table "transactions"
+  - Created indexes
+```
+
+## 5. Verify
+
+You can verify tables were created in the **Neon Console**:
+
+1. Go to your project → **SQL Editor**
+2. Run:
+
+```sql
+SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';
+```
+
+You should see: `wallets`, `cards`, `transactions`
+
+## Schema Overview
+
+```
+┌──────────────────────┐
+│       wallets        │
+├──────────────────────┤
+│ id          (uuid)   │──┐
+│ address     (text)   │  │
+│ first_seen_at (ts)   │  │
+│ total_spent_usd      │  │
+│ card_count           │  │
+└──────────────────────┘  │
+                          │
+┌──────────────────────┐  │    ┌──────────────────────┐
+│        cards         │  │    │    transactions       │
+├──────────────────────┤  │    ├──────────────────────┤
+│ id          (uuid)   │──┼───→│ card_id     (uuid)   │
+│ wallet_id   (uuid)←──┘  │    │ wallet_address(text) │
+│ wallet_address(text) │  │    │ type        (text)   │
+│ kripi_card_id (text) │  │    │ amount_usd           │
+│ name_on_card  (text) │  │    │ card_amount_usd      │
+│ email       (text)   │  │    │ fee_usd              │
+│ initial_amount_usd   │  │    │ kripi_fee_usd        │
+│ current_balance_usd  │  │    │ tx_hash     (text)   │
+│ status      (text)   │  │    │ status      (text)   │
+│ created_at  (ts)     │  │    │ error_message (text) │
+│ updated_at  (ts)     │  │    │ created_at  (ts)     │
+└──────────────────────┘  │    └──────────────────────┘
+                          │
+```
+
+## Migrations (Optional)
+
+If you prefer versioned migrations instead of `db:push`:
+
+```bash
+# Generate migration files from schema changes
+npm run db:generate
+
+# Apply migrations
+npm run db:migrate
+```
+
+Migration files are saved to `drizzle/migrations/`.
+
+## Neon Free Tier Limits
+
+| Resource  | Limit             |
+| --------- | ----------------- |
+| Compute   | 191.9 hours/month |
+| Storage   | 512 MB            |
+| Branches  | 10                |
+| Databases | Unlimited         |
+
+This is more than enough for an MVP. The compute auto-suspends after 5 min of inactivity and resumes on the next query (~500ms cold start).
+
+## Troubleshooting
+
+**"Connection refused"**
+
+- Check that `?sslmode=require` is in your connection string
+- Verify the endpoint ID matches your Neon project
+
+**"Password authentication failed"**
+
+- Reset your password in Neon Console → **Connection Details** → **Reset Password**
+- Update `DATABASE_URL` in `.env`
+
+**"Relation does not exist"**
+
+- Run `npm run db:push` to create tables
+- Check you're connecting to the correct database name