rafid-agent-api

# Rafid Property Intelligence — agent-native property and facility intelligence

Rafid provides deterministic property intelligence for autonomous AI agents, starting with OMR calculations for the Oman market. **AI agents are the primary consumer of this product, not human SaaS users.** MCP and x402 are the primary interfaces; the `X-API-Key` REST routes are the underlying transport and a compatibility layer for callers that can't do MCP or x402 yet. This MVP does not fetch market data, provide investment recommendations, or (outside x402) collect payments.

The intended flow for an agent is: **discover** a capability → **select** the right tool → **pay per call** over x402 (or authenticate with an API key) → **execute** → get a **structured, machine-readable** result. No account, dashboard or subscription is required for either access model, and none is planned — see "Design constraints" below.

## Agent discovery

An agent (or an agent marketplace/directory crawler) can start from any of the following; all are public, unauthenticated, always present, and contain no secrets (no wallet private keys, no API keys, no usage data for other customers):

| Endpoint | Purpose |
|---|---|
| `GET /agent.json` | The full agent manifest: product identity, every supported protocol (MCP, x402, REST) and its role, x402 terms, and the complete tool catalog with full input/output JSON Schemas. Start here. |
| `GET /.well-known/ai-plugin.json` | Manifest in the legacy OpenAI ChatGPT-plugin convention, for tooling that still discovers services this way. |
| `GET /.well-known/agent.json` | An Agent Card in the Agent2Agent (A2A) protocol's convention, listing each tool as a `skill`. |
| `GET /llms.txt` | A plain-text briefing for an LLM-based agent: what Rafid does, every tool and how to call it, pricing, the x402 model, and known limitations — no JSON parsing required. |
| `GET /api/v1/capabilities` | The machine-first capability registry: name, description, `whenToUse`, price, schemas and examples for every tool — optimized for a model to decide what to call, not for a human to read. |
| `GET /api/v1/mcp/status` | Factual MCP status: which transports are live (`stdio` always, `http` only when `MCP_REMOTE_ENABLED=true`), the tool count, and the remote endpoint path if any. |
| `GET /api/v1/agent` | Legacy service-metadata endpoint (kept for backward compatibility); superseded by `/agent.json` above. |
| `GET /api/v1/pricing` | The full price list (USD, pay-per-call), sourced from one catalog shared by every code path — never duplicated or out of sync. |
| `GET /api/v1/tools` | Legacy tool catalog (kept for backward compatibility); superseded by `/api/v1/capabilities` above. |

Every one of these is generated from the single capability registry in `src/domain/capabilities.ts` — see "Capability registry" below — so they can never disagree with each other or with what a call actually does.

Once a tool is chosen, call it with an `X-API-Key` header, or — when `X402_ENABLED=true` — call its `/api/v1/x402/...` twin with no key and pay per call on-chain instead (see "Pay-per-call via x402" below).

A human visiting `/` in a browser instead gets a short landing page (agent integration examples, tool list, pricing, links to docs); agents and scripts that send `Accept: application/json` keep getting the original JSON discovery payload — see "Landing page" below.

## Design constraints

This product is deliberately agent-native, not a human SaaS dashboard. It does not have, and is not planned to have, user accounts, a dashboard, subscriptions, Stripe billing, or a billing portal. The `X-API-Key` route family is a compatibility transport for callers that authenticate that way, not an invitation to build account management around it.

## Customer storage phase

PostgreSQL-backed customers, hashed keys, usage tracking and per-customer limits are now available. See [activation and administration](docs/customers.md). Existing env-key development mode remains unchanged; production requires `AUTH_MODE=postgres`. No payment collection is implemented outside x402 (see below).

## Deploy on Vercel

The Express entry point exports the app when `VERCEL=1` and keeps the normal port listener for local runs. `vercel.json` pins the function to `iad1` near the current US East Neon database and limits requests to 15 seconds. `.vercelignore` prevents the local `.env`, caches and generated files from being uploaded.

Production API: <https://api.rafidsystem.com>  
Landing page: <https://api.rafidsystem.com/> (browsers) / same URL with `Accept: application/json` (agents)  
Health: <https://api.rafidsystem.com/api/v1/health>  
OpenAPI: <https://api.rafidsystem.com/openapi.json>  
Agent metadata: <https://api.rafidsystem.com/api/v1/agent>

Connect the repository directory to a Vercel project, attach the Neon Marketplace database, and configure these Production environment variables:

```dotenv
AUTH_MODE=postgres
NODE_ENV=production
LOG_LEVEL=info
X402_ENABLED=false
DATABASE_URL=<sensitive pooled Neon URL with sslmode=verify-full>
```

The Neon integration may inject `DATABASE_URL`; verify that it points to the rotated credential and pooled endpoint. Mark manually added database values as sensitive. Do not upload `.env` or use the previously exposed password. Deploy with Vercel CLI or a connected Git repository, then verify `/api/v1/health`, `/openapi.json`, `/api/v1/agent`, an authenticated analysis request, and the PostgreSQL usage record. The local stdio MCP process is not deployed by this Express function.

To also accept pay-per-call crypto payments, set `X402_ENABLED=true` and `X402_WALLET_ADDRESS=<a 0x-prefixed EVM address you control>` in Production. Leave `X402_ENABLED=false` (the default) until you are ready to receive real payments; see Configuration and the "Pay-per-call via x402" section below. On Base mainnet (`eip155:8453`) also set `CDP_API_KEY_ID`/`CDP_API_KEY_SECRET` (see Configuration).

## Prerequisites and quick start

Use Node.js 24+ and npm. From the repository root:

```powershell
Set-Location 'C:\Projects\rafid-agent-api'
npm.cmd ci --cache .npm-cache
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
```

Copy the generated key into `RAFID_API_KEYS` in `.env`. Keep it private. A blank or short key prevents HTTP startup. Multiple keys are comma-separated. On macOS/Linux use `npm` and `cp .env.example .env`.

```powershell
npm.cmd run dev
```

Development loads `.env` and watches TypeScript sources. For a compiled run:

```powershell
npm.cmd run typecheck
npm.cmd run build
npm.cmd test
npm.cmd start
```

`npm test` first builds and then runs service, live HTTP, agent-marketplace, OpenAPI contract, and compiled MCP stdio tests. `npm start` loads `.env` and runs `dist/server.js`; dependencies are pinned in `package-lock.json`.

## Configuration

| Variable | Default / behavior |
|---|---|
| PORT | 8787 |
| NODE_ENV | development; accepts development, test, production |
| RAFID_API_KEYS | Required for REST; random keys of at least 24 characters |
| API_KEY | Legacy fallback when RAFID_API_KEYS is empty |
| LOG_LEVEL | info; error logs only HTTP/tool 5xx completions; silent disables request logs |
| X402_ENABLED | false; true enables pay-per-call crypto payments at `/api/v1/x402/...` (no API key needed there) and requires X402_WALLET_ADDRESS. Disabled (the default) never affects normal API-key calls — the x402 route family simply doesn't exist and is omitted from discovery/`/openapi.json` |
| X402_NETWORK | eip155:84532 (Base Sepolia testnet); the public facilitator only settles this network for EVM. Any other network, e.g. eip155:8453 (Base mainnet), requires CDP_API_KEY_ID/CDP_API_KEY_SECRET below |
| X402_WALLET_ADDRESS | Empty; required 0x-prefixed EVM address that receives payments when X402_ENABLED=true |
| X402_FACILITATOR_URL | https://x402.org/facilitator; must be an https URL |
| CDP_API_KEY_ID | Empty; Coinbase Developer Platform API key ID (Ed25519 Secret API Key). Required together with CDP_API_KEY_SECRET for any network besides Base Sepolia |
| CDP_API_KEY_SECRET | Empty; Coinbase Developer Platform API key secret. When both CDP vars are set, they take over as the facilitator (X402_FACILITATOR_URL is then ignored) |
| MCP_REMOTE_ENABLED | true; mounts the Streamable HTTP MCP transport at `/mcp`. false unmounts it entirely (404, and every manifest/llms.txt advertises stdio only) — a rollback switch with no code change |
| RAFID_LOGO_URL | Empty; `logo_url` in `/.well-known/ai-plugin.json`. Left blank rather than fabricated |
| RAFID_CONTACT_EMAIL | Empty; `contact_email` in `/.well-known/ai-plugin.json` |
| RAFID_LEGAL_INFO_URL | Empty; `legal_info_url` in `/.well-known/ai-plugin.json` |
| USAGE_REPOSITORY | console (default: one JSON line to stderr per call); memory (local inspection only, lost on restart); postgres (durable `rafid_agent_usage` table — requires DATABASE_URL, independent of AUTH_MODE) |
| RATE_LIMIT_ENABLED | true; per-process, IP-keyed rate limiting on discovery, x402 and remote MCP routes (three independent budgets). false disables it (development/tests) |
| RATE_LIMIT_WINDOW_MS | 60000 (one minute) |
| RATE_LIMIT_MAX | 60 requests per window, per IP, per route group |
| OMAN_PROPERTY_DATA_MODE | manual (default); database; composite. Which Oman property data source(s) `analyze_oman_property` actually queries — see "Production Oman market data" below |
| OMAN_MARKET_DATABASE_URL | Empty; falls back to `DATABASE_URL` when unset. Lets the market-data database be separate from the customer/billing database if desired |
| OMAN_MARKET_STALE_DAYS | 365; a comparable sample whose median age exceeds this is flagged `staleMarketData: true` and its confidence score is deterministically reduced. Independent of and shorter than `comparables.ts`'s 540-day hard recency cutoff (which excludes a record from the pool entirely) |
| OMAN_MARKET_