# Agent API

This app visualizes token activity. Agent-friendly data endpoints live in the `chkn_store` service.

Base URL: https://chkn.computer
OpenAPI: `GET /openapi.json`
Docs UI: `GET /docs`

Retention: 48 hours
Slots/sec: ~2.5
Rate limit: 60 requests/minute per IP (applies to `/api/agent/*`)

Responses never include layout/graph data.

## Errors

All agent endpoints may return:

```json
{"error":"invalid_mint"|"invalid_range"|"rate_limited","message":"..."}
```

## Endpoints

### `GET /api/agent/info`

Returns:

```json
{ "currentSlot": 0, "slot24hAgo": 0, "oldestSlot": 0, "retentionHours": 48, "slotsPerSecond": 2.5, "timestamp": 0 }
```

### `GET /api/agent/transfers`

Query params:
- `mint` (required)
- `start` (slot, optional)
- `end` (slot, optional)
- `limit` (default 1000, max 10000)
- `offset` (default 0)

Returns:

```json
{
  "mint": "...",
  "startSlot": 0,
  "endSlot": 0,
  "count": 0,
  "hasMore": false,
  "transfers": [
    { "from": "...", "to": "...", "amount": 0, "amountUsd": 0, "slot": 0, "timestamp": 0, "signature": "...", "source": "transfer" }
  ]
}
```

### `GET /api/agent/swaps`

Query params:
- `mint` (required)
- `start` (slot, optional)
- `end` (slot, optional)
- `side` (optional: `buy` | `sell`)
- `limit` (default 1000, max 10000)
- `offset` (default 0)

Returns:

```json
{
  "mint": "...",
  "startSlot": 0,
  "endSlot": 0,
  "count": 0,
  "hasMore": false,
  "swaps": [
    { "wallet": "...", "side": "buy", "amount": 0, "amountUsd": 0, "priceUsd": 0, "slot": 0, "timestamp": 0, "signature": "...", "dex": null }
  ]
}
```

Notes:
- Swaps are derived from records where source/kind is `dex`.
- `wallet` is chosen based on `side` (`buy` => `to`, `sell` => `from`).

## Example calls

```bash
curl "https://chkn.computer/api/agent/info"

curl "https://chkn.computer/api/agent/transfers?mint=<MINT>&start=<SLOT>&end=<SLOT>&limit=1000&offset=0"

curl "https://chkn.computer/api/agent/swaps?mint=<MINT>&start=<SLOT>&end=<SLOT>&side=buy&limit=1000&offset=0"
```