# AgenticPlace Technical Reference

## Database

MariaDB 10.3+ / MySQL 5.7+ with `pdo_mysql`. Three tables:

### agents (126,000+ records)

| Column | Type | Index | Default |
|--------|------|-------|---------|
| agent_id | VARCHAR(255) | PK | |
| token_id | INT | idx_agents_token | |
| chain_id | INT | idx_agents_chain | |
| owner_address | VARCHAR(255) | idx_agents_owner | '' |
| name | TEXT | FULLTEXT | |
| description | TEXT | | |
| image_url | TEXT | | |
| is_verified | TINYINT(1) | idx_agents_verified | 0 |
| star_count | INT | | 0 |
| x402_supported | TINYINT(1) | | 0 |
| total_score | INT | idx_agents_score | 0 |
| total_feedbacks | INT | | 0 |
| average_score | FLOAT | | 0 |
| supported_protocols | TEXT | | '' |
| created_at | DATETIME | | NULL |
| updated_at | DATETIME | | CURRENT_TIMESTAMP |
| indexed_at | DATETIME | | CURRENT_TIMESTAMP |

### allchains (2,510 records)

| Column | Type | Index | Notes |
|--------|------|-------|-------|
| chain_id | BIGINT | PK | EVM chain ID |
| name | VARCHAR(255) | idx_allchains_name | |
| chain | VARCHAR(50) | | Symbol |
| chain_type | VARCHAR(20) | | L1/L2/Sidechain |
| status | VARCHAR(20) | | active/deprecated |
| is_testnet | TINYINT(1) | idx_allchains_testnet | |
| native_currency | JSON | | {name, symbol, decimals} |
| rpc_urls | TEXT | | Pipe-separated |
| rpc_count | INT | | |
| explorers | JSON | | Explorer objects |
| explorer_count | INT | | |
| faucets | TEXT | | Pipe-separated |
| faucet_count | INT | | |
| icon_url | TEXT | | |
| info_url | TEXT | | |
| short_name | VARCHAR(50) | | e.g. "eth" |
| network_id | BIGINT | | |
| slip44 | BIGINT | | BIP44 coin type |
| native_price | DECIMAL(20,8) | | USD |
| market_cap | DECIMAL(30,2) | idx_allchains_mcap | USD |
| volume_24h | DECIMAL(30,2) | | |
| price_change_24h | DECIMAL(10,4) | | % |
| protocol_symbol | VARCHAR(20) | | Governance token |
| protocol_price | DECIMAL(20,8) | | USD |
| metamask_native | TINYINT(1) | | |
| non_evm | TINYINT(1) | | |
| last_updated | DATETIME | | CURRENT_TIMESTAMP |

### scan_status

| Column | Type | Purpose |
|--------|------|---------|
| id | INT PK AUTO_INCREMENT | |
| last_page | INT | Last 8004scan page fetched |
| total_remote | INT | Total agents on 8004scan |
| total_local | INT | Total in local DB |
| is_complete | TINYINT(1) | Full sync finished |
| started_at | DATETIME | |
| updated_at | DATETIME | |

## REST API

Base: `https://agenticplace.pythai.net/api`

### GET /api/stats

Returns agent counts, chain breakdown, scan status, and live 8004scan remote count (cached 5 min).

```json
{
  "success": true,
  "data": {
    "total_local": 115498,
    "total_remote": 126336,
    "daily_new": 42,
    "chains": [{"chain_id": 8453, "cnt": 52341, "name": "Base", "short_name": "base"}],
    "verified": 1669,
    "x402": 0,
    "scan": {"last_page": 1155, "total_remote": 126336, "is_complete": true, "updated_at": "2026-03-27..."}
  }
}
```

### GET /api/agents

Paginated agent query with search, filtering, and sorting.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| page | int | 1 | Page number |
| limit | int | 100 | Results per page (max 1000) |
| q | string | | Search name, description, owner_address |
| chain | int | | Filter by chain_id |
| sort | string | token_id | Sort column: token_id, name, chain_id, total_score, created_at |
| dir | string | asc | Sort direction: asc, desc |
| verified | 1 | | Only verified agents |
| x402 | 1 | | Only x402-supported agents |

```json
{
  "success": true,
  "data": [{"agent_id": "8453_1234", "token_id": 1234, "chain_id": 8453, "name": "..."}],
  "meta": {"page": 1, "limit": 100, "total": 115498, "pages": 1155, "hasMore": true}
}
```

### POST /api/scan

Fetch a batch of agents from 8004scan.io and upsert into local DB. Called automatically by the frontend auto-scan engine.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| pages | int | 5 | Pages to fetch per call (1-20) |
| reset | "1" | | Restart scan from page 1 |

Returns progress status, events array, and completion state.

### POST /api/register-local

Insert a freshly minted agent into the local DB immediately after on-chain mint. Uses `ON DUPLICATE KEY UPDATE` for idempotency.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| agent_id | string | yes | Unique agent identifier |
| token_id | int | | ASA ID or token ID |
| chain_id | int | | Chain ID (416001 for Algorand) |
| owner_address | string | | Wallet address |
| name | string | yes | Agent name |
| description | string | | |
| image_url | string | | |
| supported_protocols | string | | Comma-separated: MCP,A2A,Web |
| x402_supported | bool | | |

### GET /api/confirm

Poll 8004scan for a specific agent. Used after local mint to track external indexing.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| agent_id | string | yes | Agent to check |

```json
{"success": true, "confirmed": true, "agent_id": "algorand:12345"}
```

### GET /api/download

Streams the full agent list as a JSON download. Cursor-based, 5000-record batches.

### GET /api/export

Export agents and/or chains in multiple formats.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| table | string | both | agents, allchains, or both |
| format | string | json | csv, json, md, txt |
| download | 1 | | Force file download headers |
| pretty | 1 | | Pretty-print JSON |

### GET /api/setup?key=...

Creates database schema. Requires `SETUP_KEY` env var or default `setup-agenticplace-2026`.

### GET /api/import?key=...

Bulk imports from `data/agents-export.csv` and `data/allchains-export.csv`. 500-record batches with transaction rollback on error. 10-minute timeout.

## Auto-Scan Engine

Browser-driven adaptive polling (no cron required). Starts automatically when `/browse` loads.

### Intervals

| Condition | Interval | Trigger |
|-----------|----------|---------|
| Catching up (not synced) | 3 seconds | `is_complete = false` |
| High activity | 15 seconds | `daily_new > 500` or new agents found |
| Active | 30 seconds | `daily_new > 50` |
| Normal (default) | 60 seconds | `daily_new > 0` |
| Low activity | 2 minutes | `daily_new = 0` |

### Rate Limits

- 8004scan API: 10 requests/minute (enforced server-side with 6.5s delay)
- Each scan tick fetches 2 pages = 200 agents
- Minimum real-world tick: ~15 seconds (due to API rate limit)

### Flow

1. `init()` calls `loadStats()` then `startAutoScan()`
2. `autoScanTick()` POSTs to `/api/scan` with `{pages: 2}`
3. Backend fetches 2 pages from 8004scan, upserts into MariaDB
4. Frontend updates ring, counts, and feed
5. `scheduleNextScan()` calculates next interval from activity level
6. If not fully synced, enters burst mode (3s ticks until caught up)

## Instant Mint Flow

1. User mints ASA on Algorand (via register.html)
2. On-chain confirmation received (4 blocks, ~16 seconds)
3. Frontend POSTs agent data to `/api/register-local`
4. Agent appears immediately in `/browse`
5. Frontend polls `/api/confirm` every 10 seconds
6. When 8004scan indexes the agent, indicator turns green
7. Local record updated with 8004scan verification data

## Security

### .htaccess

- HTTPS redirect (301)
- `X-Frame-Options: SAMEORIGIN`
- `X-Content-Type-Options: nosniff`
- `Referrer-Policy: strict-origin-when-cross-origin`
- `config.php` blocked from direct access
- `.csv` files blocked from direct access
- Gzip compression for HTML, CSS, JS, JSON
- Static asset caching: CSS/JS 1 week, HTML no-cache

### CORS

Allowed origins: `localhost`, `127.0.0.1`, `https://agenticplace.pythai.net`, `localhost:9876`. Same-origin requests always allowed.

### Authentication

Setup and import endpoints require `SETUP_KEY` (env var or default). All other endpoints are public read-only. Write endpoints (`register-local`, `scan`) validate input but have no auth — they are called from the frontend.

## External Dependencies

| Service | Purpose | Rate Limit |
|---------|---------|------------|
| 8004scan.io | ERC-8004 agent data | 10 req/min |
| Nodely (mainnet-api.4160.nodely.dev) | Algorand algod | Public tier |
| unpkg.com | Pera SDK + algosdk CDN | Public CDN |
| localhost:9876 | Parsec Wallet WebSocket | Local only |
| Google Fonts | Inter + Fira Code | Public CDN |