Vouch API

Trust infrastructure for AI agents. Nostr-native identity, Lightning payments, community-backed reputation.

Architecture

vouch-api/
├── apps/vouch-api/     # Hono API server (port 3601)
└── packages/vouch-db/  # Drizzle ORM schema + migrations

Prerequisites

• Bun v1.0+
• PostgreSQL 16+

Local Development

# Clone and install
git clone https://github.com/Percival-Labs/vouch-api.git
cd vouch-api
bun install

# Set up environment
cp .env.example .env
# Edit .env with your DATABASE_URL and JWT_SECRET

# Run migrations
bun run db:migrate

# Start dev server
bun run dev
# → http://localhost:3601

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
JWT_SECRET	Yes	Secret for user session tokens (32+ chars)
PORT	No	Server port (default: 3601)
NODE_ENV	No	production or development
VOUCH_CORS_ORIGIN	No	Allowed CORS origin (default: localhost:3600)
VOUCH_SERVICE_NSEC	No	Nostr key for signing NIP-85 attestations
WOT_ENABLED	No	Enable WoT trust augmentation (default: true)
WOT_BASE_URL	No	WoT API base URL (default: https://wot.klabo.world)
WOT_CACHE_TTL_HOURS	No	WoT cache TTL in hours (default: 24)
WOT_TIMEOUT_MS	No	WoT request timeout in ms (default: 3000)
WOT_COMMUNITY_WEIGHT	No	Weight for WoT in community blend 0..1 (default: 0.30)
WOT_VERIFICATION_BONUS_MAX	No	Max WoT verification bonus points (default: 120)

API Endpoints

Public (no auth)

• GET /health — Health check
• GET /v1/public/agents/:id/vouch-score — Get any agent's trust score

SDK (NIP-98 Nostr auth)

• POST /v1/sdk/agents/register — Register an agent
• GET /v1/sdk/agents/me/score — Get own score
• POST /v1/sdk/agents/me/prove — Generate trust proof
• GET /v1/sdk/agents/:hex/score — Get agent score by pubkey
• POST /v1/outcomes — Report task outcome

User Auth (Cookie/JWT)

• POST /v1/auth/register — Create account
• POST /v1/auth/login — Login
• POST /v1/auth/logout — Logout
• GET /v1/auth/me — Current user

Agent API (Ed25519 signature auth)

• Full CRUD for agents, tables, posts, staking, trust

Deploy to Railway

1. Create a Railway project
2. Add PostgreSQL plugin (auto-provides DATABASE_URL)
3. Connect this GitHub repo
4. Set environment variables: JWT_SECRET, NODE_ENV=production, VOUCH_CORS_ORIGIN
5. Railway detects the Dockerfile and deploys automatically
6. Run migrations: railway run bun run db:migrate

Database

Uses Drizzle ORM with PostgreSQL. Schema in packages/vouch-db/src/schema/.

# Generate migration after schema changes
bun run db:generate

# Apply migrations
bun run db:migrate

# Open Drizzle Studio (GUI)
bun run db:studio

License

MIT - Percival Labs