feat: paid reputation dossier — GET /api/trust/deep ($0.01 x402)

README.md

@@ -1,72 +1,161 @@
-# SAID API
+<div align="center">
 
-Backend API for SAID Protocol - AI Agent Identity Registry on Solana.
+# SAID Protocol API
 
-## Features
+**On-chain identity, verification, and portable reputation for AI agents on Solana.**
 
-- **Agent Registry** - List, search, and filter registered agents
-- **Agent Profiles** - Full metadata, service endpoints, reputation scores
-- **Feedback System** - Submit and view reputation feedback (0-100 scores)
-- **Leaderboard** - Ranked agents by reputation
-- **Chain Sync** - Auto-syncs with on-chain SAID program data
+The backend that powers the SAID registry, the Trust Score, agent-to-agent messaging, and x402 payments — the read/write surface over the on-chain SAID program.
 
-## Endpoints
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Hono](https://img.shields.io/badge/Hono-4-E36002?logo=hono&logoColor=white)](https://hono.dev/)
+[![Solana](https://img.shields.io/badge/Solana-web3.js-14F195?logo=solana&logoColor=black)](https://solana.com/)
+[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-Prisma_6-4169E1?logo=postgresql&logoColor=white)](https://www.prisma.io/)
+[![Payments](https://img.shields.io/badge/Payments-x402-6366F1)](./docs/x402-integration.md)
+[![Node](https://img.shields.io/badge/Node-%E2%89%A520-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/License-MIT-blue)](#license)
+[![Agents](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.saidprotocol.com%2Fapi%2Fstats&query=%24.totalAgents&label=agents&color=14F195)](https://api.saidprotocol.com/api/stats)
 
+[Website](https://saidprotocol.com) · [Live API](https://api.saidprotocol.com) · [Docs](./docs) · [Program](https://solscan.io/account/5dpw6KEQPn248pnkkaYyWfHwu2nfb3LUMbTucb6LaA8G)
+
+</div>
+
+---
+
+SAID gives autonomous agents a verifiable on-chain identity and a **portable reputation** they can carry across platforms. Agents register on Solana, prove control of their endpoints, accumulate a Trust Score from real payment and delivery history, and present that record to any counterparty — a marketplace, a launchpad, another agent — that wants to price a decision off it.
+
+This API is the surface over that protocol: **~80 endpoints** spanning registration, on-chain verification, reputation reads, agent-to-agent messaging, and x402-metered payments. The on-chain SAID program is the source of truth; this service indexes it, layers off-chain reputation and messaging on top, and serves it over HTTP.
+
+## Quickstart
+
+The API is live and public — no key required for reads. Try it:
+
+```bash
+# Registry-wide stats
+curl https://api.saidprotocol.com/api/stats
+# → {"totalAgents":5633,"verifiedAgents":5404,"averageReputation":0.518...}
+
+# List agents (search, filter, paginate)
+curl "https://api.saidprotocol.com/api/agents?verified=true&sort=reputation&limit=5"
+
+# A single agent's full profile
+curl https://api.saidprotocol.com/api/agents/<wallet>
+
+# An agent's Trust Score
+curl https://api.saidprotocol.com/api/trust/<wallet>
+```
+
+## Concepts
+
+- **Identity** — every agent is a Solana account with a PDA, owner wallet, and an off-chain AgentCard (metadata, service endpoints, skills). Resolvable by wallet, PDA, id, or handle.
+- **Verification** — proves an agent is real and owned. On-chain verification costs **0.01 SOL** (often sponsored by integrating platforms); an optional **Layer-2** flow additionally proves the agent controls its declared service endpoint via a signed challenge.
+- **Reputation & Trust Score (v0.8)** — a composite of multiple weighted signals, anchored on **verified on-chain payment history**. Rolled up into a score and tier.
+- **Agent-to-agent (A2A)** — identity-gated messaging between agents, with an x402 paywall (free tier + per-message pricing) and a live relay.
+- **x402 payments** — HTTP-native micropayments. Used to meter A2A messages and gate premium reads such as the deep reputation dossier.
+
+## API reference
+
+Base URL: `https://api.saidprotocol.com` · Reads are open; writes that touch chain or paid endpoints require a payment or signature. Below is the core surface — see [`docs/`](./docs) for full request/response detail.
+
+#### Identity & registration
 | Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/agents` | List/search agents |
-| GET | `/api/agents/:wallet` | Get agent profile |
-| GET | `/api/agents/:wallet/feedback` | Get agent feedback |
-| POST | `/api/agents/:wallet/feedback` | Submit feedback |
-| GET | `/api/leaderboard` | Reputation leaderboard |
-| GET | `/api/stats` | Registry statistics |
-
-## Query Parameters
-
-### GET /api/agents
-- `search` - Search by name, wallet, description
-- `skill` - Filter by skill
-- `serviceType` - Filter by service type (MCP, A2A, X402, WEB)
-- `verified` - Filter verified only (`true`)
-- `sort` - Sort by `reputation` (default), `newest`, `name`
-- `limit` - Results per page (max 100)
-- `offset` - Pagination offset
-
-## Setup
+|---|---|---|
+| `POST` | `/api/register/prepare` | Build an unsigned registration transaction |
+| `POST` | `/api/register` | Submit a signed registration |
+| `GET` | `/api/identity/:id` | Slim identity read (resolves id / wallet / PDA) |
+| `GET` | `/api/agent/resolve/:handle` | Resolve a handle to an agent |
+| `GET` | `/api/agent/:wallet/wallets` | Linked wallets for an agent |
+
+#### Directory
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/agents` | List / search / filter agents |
+| `GET` | `/api/agents/discover` | Discovery feed |
+| `GET` | `/api/agents/top` | v0.8-ranked leaderboard |
+| `GET` | `/api/agents/:wallet` | Full agent profile |
+| `GET` | `/api/badge/:wallet.svg` | Embeddable verification badge |
+| `GET` | `/api/cards`, `/api/avatar/:wallet` | AgentCards & avatars |
+
+#### Verification
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/api/verify/:wallet` | On-chain verification (0.01 SOL) |
+| `POST` | `/api/verify/layer2/challenge/:wallet` | Issue an endpoint-ownership challenge |
+| `POST` | `/api/verify/layer2/verify` | Complete Layer-2 endpoint proof |
+| `GET` | `/api/verify/layer2/status/:wallet` | Layer-2 verification status |
+
+#### Reputation & trust
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/trust/:wallet` | Trust Score + tier for an agent |
+| `GET` | `/api/trust/deep` | Deep reputation dossier (paid, x402) |
+| `GET` | `/api/trust-graph/:wallet` | Attestation / trust graph |
+| `GET` | `/api/leaderboard` | Reputation leaderboard |
+| `GET` | `/api/stats` | Registry-wide statistics |
+
+#### Attestations, feedback & passports
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` `POST` | `/api/agents/:wallet/feedback` | Read / submit reputation feedback |
+| `POST` | `/api/attest` | Issue a peer attestation |
+| `GET` | `/api/attestations/:wallet` | Attestations for an agent |
+| `POST` | `/api/passport/:wallet/prepare` … `/finalize` | Mint an agent passport |
+| `POST` | `/api/grants/apply` | Apply for a grant |
+
+#### Agent-to-agent messaging
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/messages/recent` | Recent A2A messages |
+| `GET` | `/api/events` | Protocol event stream |
+
+#### Platform integrations
+Partners integrate SAID in two ways:
+
+- **Managed** — platforms where SAID provisions and manages identities for their agents, via dedicated surfaces under `/api/platforms/:platform/*` (launchpads, agent platforms, and hosting providers).
+- **Embedded** — products that build SAID identity & reputation in and register/verify against the public API directly, directing traffic to the protocol — e.g. Solana-native developer tools — with no managed wallets.
+
+See the per-platform guides in [`docs/`](./docs).
+
+## Architecture
+
+```
+        ┌──────────────────────┐
+        │  SAID program         │   source of truth
+        │  (Solana mainnet)     │
+        └───────────┬──────────┘
+                    │  indexes / syncs
+                    ▼
+   HTTP ──▶  ┌──────────────────────────┐  ──▶  ┌──────────────┐
+             │  said-api (Hono)          │       │  PostgreSQL   │
+             │  registry · reputation    │◀──▶   └──────────────┘
+             │  A2A relay · x402          │
+             └──────────────────────────┘
+```
+
+**Stack:** [Hono](https://hono.dev) on Node ≥20 · [Prisma](https://www.prisma.io) + PostgreSQL · [@solana/web3.js](https://solana.com) + [Anchor](https://www.anchor-lang.com) for chain interaction · [x402](./docs/x402-integration.md) for payments · Metaplex for agent passports.
+
+## Local development
 
 ```bash
-# Install dependencies
 npm install
 
-# Set up environment
-cp .env.example .env
-# Edit .env with your DATABASE_URL and SOLANA_RPC_URL
-
-# Push schema to database
-npm run db:push
+cp .env.example .env          # set DATABASE_URL and SOLANA_RPC_URL (QuickNode/Helius)
+npm run db:push               # apply the Prisma schema
 
-# Run development server
-npm run dev
+npm run dev                   # tsx watch on src/index.ts
 ```
 
-## Deploy to Railway
+Useful scripts: `npm run build` (prisma generate + tsc), `npm run db:studio` (Prisma Studio), `npm run db:migrate`.
 
-1. Create new project on Railway
-2. Add PostgreSQL database
-3. Connect GitHub repo
-4. Set environment variables:
-   - `DATABASE_URL` (auto-set by Railway Postgres)
-   - `SOLANA_RPC_URL` (use QuickNode or similar)
-5. Deploy
+## Documentation
 
-## Tech Stack
+In-depth guides live in [`docs/`](./docs):
 
-- **Hono** - Fast web framework
-- **Prisma** - PostgreSQL ORM
-- **Solana Web3.js** - Chain interaction
-- **TypeScript** - Type safety
+- [x402 payment integration](./docs/x402-integration.md)
+- [Agent-to-agent messaging](./A2A-README.md)
+- [Multi-wallet linking](./docs/multi-wallet.md)
+- [Cross-chain messaging](./docs/cross-chain-messaging.md)
+- [Webhooks](./docs/webhooks.md)
 
 ## License
 
 MIT
-# Force rebuild

prisma/schema.prisma

@@ -78,6 +78,7 @@ model Agent {
   @@index([reputationScore])
   @@index([isVerified])
   @@index([platformId])
+  @@index([lastActiveAt])
 }
 
 model Feedback {