## Forever Moments Public API (v1)

This API is a **stable, public, read-only** surface for building third-party frontends on top of Forever Moments contracts and indexed data.

### Base URLs

- **OpenAPI JSON**: `/api/public/v1/openapi.json`
- **Swagger UI**: `/api/public/v1/docs`
- **This guide**: `/api/public/v1/README.md`

### Response format

- **Success**:
  - `success: true`
  - `data`: payload
  - `meta`: pagination/diagnostics (optional)
- **Error**:
  - `success: false`
  - `error.code`, `error.message`

### CORS

All public endpoints include `Access-Control-Allow-Origin: *`, so browser-based frontends can call them directly.

### Pagination

Most list endpoints use:

- `limit` (max 100)
- `offset` (0-based)

### Collections

List collections:

```bash
curl "https://your-domain.com/api/public/v1/collections?limit=21&offset=0&sortBy=most-recent"
```

Count only:

```bash
curl "https://your-domain.com/api/public/v1/collections?countOnly=true"
```

Fetch by ids:

```bash
curl -X POST "https://your-domain.com/api/public/v1/collections/by-ids" \
  -H "Content-Type: application/json" \
  -d '{"collectionIds":["0xabc...","0xdef..."]}'
```

### Moments

List moments:

```bash
curl "https://your-domain.com/api/public/v1/moments?limit=21&offset=0&sortBy=most-recent"
```

Filter by owner:

```bash
curl "https://your-domain.com/api/public/v1/moments?owner=0x1234...&limit=21&offset=0"
```

Moment detail:

```bash
curl "https://your-domain.com/api/public/v1/moments/0xMomentAddress..."
```

Moment likes:

```bash
curl "https://your-domain.com/api/public/v1/moments/0xMomentAddress.../likes?limit=20&offset=0"
```

Moment comments:

```bash
curl "https://your-domain.com/api/public/v1/moments/0xMomentAddress.../comments?limit=20&offset=0"
```

Optional refresh (best-effort pull from indexer before serving):

```bash
curl "https://your-domain.com/api/public/v1/moments/0xMomentAddress.../comments?limit=20&offset=0&refresh=true"
```

Comments payload fields:

- `id`: unique comment event id
- `commentId`: on-chain comment id (string)
- `parentId`: parent comment id (string, `"0"` means top-level)
- `author`: commenter address
- `operator`: operator address from event
- `amountWei`: likes amount attached to the comment (wei, string)
- `text`: comment text
- `txHash`: transaction hash
- `logIndex`: log index within the transaction
- `blockNumber`: block number (string)
- `blockTimestamp`: unix seconds
- `source`: data source marker (`v3`/`v4` etc.)
- `authorProfile`: `{ id, name, avatar } | null` (best-effort from profile table)

Example shape:

```json
{
  "success": true,
  "data": {
    "comments": [
      {
        "id": "0x...",
        "commentId": "12",
        "parentId": "0",
        "author": "0xabc...",
        "operator": "0xdef...",
        "amountWei": "1000000000000000000",
        "text": "Beautiful shot",
        "txHash": "0x...",
        "logIndex": 3,
        "blockNumber": "1234567",
        "blockTimestamp": 1730000000,
        "source": "v3",
        "authorProfile": { "id": "0xabc...", "name": "Alice", "avatar": "https://..." }
      }
    ]
  },
  "meta": { "total": 1, "limit": 20, "offset": 0, "hasMore": false }
}
```

### Profiles

Batch fetch profile cards:

```bash
curl "https://your-domain.com/api/public/v1/profiles?addresses=0xabc...,0xdef..."
```

Profile detail:

```bash
curl "https://your-domain.com/api/public/v1/profiles/0xabc..."
```

Profile moments:

```bash
curl "https://your-domain.com/api/public/v1/profiles/0xabc.../moments?limit=20&offset=0"
```

### Marketplace

Currently listed moments:

```bash
curl "https://your-domain.com/api/public/v1/marketplace/for-sale?limit=50&sortBy=listed-recently"
```

### Likes stats

```bash
curl "https://your-domain.com/api/public/v1/likes/stats"
```