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. 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:

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:

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.

npm.cmd run dev

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

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_CACHE_TTL_MS	Empty/0 (disabled); when set, DatabaseOmanPropertyDataProvider caches a comparable-pool query in memory for this many milliseconds — see "Production Oman market data" below
OMAN_RECENT_SALES_DAYS	730 (~2 years); the window analyze_oman_property's historicalSalesContext.recentComparableSales/recentMedianPricePerSqmOMR treat as "recent" — separate from, and never affecting, comparables.ts's fixed 540-day cutoff used for the current market estimate. See "Historical sales context" below
NCSI_API_BASE_URL	https://map.ncsi.gov.om/ODPAPI (verified live base — see "Official market context (NCSI)" below)
NCSI_REQUEST_TIMEOUT_MS	8000
NCSI_CACHE_TTL_MS	21600000 (6 hours); 0 disables caching official context lookups
NCSI_REAL_ESTATE_DATASET_ID	Empty; no default — see "Official market context (NCSI)" below for why this must be operator-verified, never guessed
NCSI_FIELD_MAP_JSON	Empty; a JSON object mapping this capability's field names to the configured dataset's actual field names — see "Official market context (NCSI)" below
MARKET_DATA_INTERNAL_API_KEY	Empty; no default. Shared secret gating GET /api/v1/internal/market-data/status and .../partners — see "Partner Data Feed" below. Unset means those two routes always return 503, never a silently-open endpoint
PARTNER_FEED_STALE_DAYS	7; a partner whose latest accepted record is older than this is reported stale: true by GET /api/v1/internal/market-data/partners — a per-partner monitoring signal only, never affecting ingestion, analyze_oman_property, or any other partner's staleness

The app accepts pre-existing environment variables over .env. No live credentials are included. .env, dependencies, build output and npm cache are ignored by Git. Never commit or log CDP_API_KEY_SECRET, X402_WALLET_ADDRESS's private key (never requested or stored by this app), or DATABASE_URL.

Architecture

src/
  api/app.ts             Express application factory; no listener side effects
  api/agent.ts           Agent-marketplace discovery, pricing, tool-catalog and capability-registry builders
  api/manifest.ts        /agent.json, /.well-known/ai-plugin.json and /.well-known/agent.json builders
  api/llms-txt.ts        /llms.txt plain-text briefing builder
  api/landing.ts         Dependency-free HTML landing page for browsers
  api/openapi.ts         OpenAPI 3.1 built from shared Zod schemas
  domain/capabilities.ts The single AgentCapability registry every consumer above reads from
  domain/roadmap.ts      Planned-but-not-implemented future tools (metadata only, nothing callable)
  domain/financial.ts    Percentage/rounding helpers and maintenance defaults
  domain/oman/types.ts          Oman domain vocabulary (property types, furnished status, source types)
  domain/oman/locations.ts      Muscat area/wilayat normalization (English + Arabic aliases)
  domain/oman/comparables.ts    Comparable selection: size/bedroom/furnished tolerances, IQR outlier removal
  domain/oman/confidence.ts     Deterministic confidence scoring (never model-invented)
  domain/oman/dataProviders.ts  OmanPropertyDataProvider abstraction: Official (real NCSI context) + Listing (stub) + Manual + Database + Composite
  domain/oman/fixtures.ts       Curated/demo Muscat rental & sale benchmark dataset (clearly labeled, not live data)
  domain/oman/marketRepository.ts PropertyMarketRepository interface (engine-agnostic) + MemoryPropertyMarketRepository
  domain/oman/importPipeline.ts Validating CSV/JSON import pipeline for production market records
  domain/oman/dataQualityScore.ts Deterministic, non-LLM per-record data-quality scoring (Partner Data Feed)
  domain/oman/partners.ts       PropertyDataPartner/PartnerRepository abstraction + MemoryPartnerRepository (Partner Data Feed)
  domain/oman/cache.ts          ComparableCache interface + MemoryComparableCache (Redis-ready shape, not yet wired)
  domain/oman/config.ts         OMAN_PROPERTY_DATA_MODE / staleness threshold / cache TTL / NCSI / Partner Data Feed config readers
  domain/oman/officialContext.ts       OfficialMarketContext type + field-map-driven NCSI record adapter (never a hardcoded field name)
  domain/oman/officialContextCache.ts  OfficialMarketContextCache interface + MemoryOfficialMarketContextCache
  services/ncsi/ncsiClient.ts   NcsiClient: catalog discovery, dataset records, retries, timeout, normalized errors
  db/marketSchema.ts    PostgreSQL schema for property_market_records (independent migration ledger)
  db/marketStore.ts     PostgresPropertyMarketRepository: the production PropertyMarketRepository implementation
  db/partnerSchema.ts   PostgreSQL schema for data_partners + property_market_records partner columns (migration v2)
  db/partnerStore.ts    PostgresPartnerRepository: the production PartnerRepository implementation (shares its Pool with PostgresPropertyMarketRepository)
  api/marketDataRoutes.ts Partner Data Feed ingestion + internal status/health routes (never in the capability registry)
  middleware/partnerAuth.ts Per-partner bearer-token auth (X-Partner-Token) + internal shared-secret auth (X-Internal-Api-Key)
  marketImportCli.ts    `npm run market:import -- <file> [PARTNER_ID]` CLI entry point
  ncsiDiscoverCli.ts    `npm run ncsi:discover` CLI: lists NCSI's live catalog and flags real-estate-relevant datasets
  schemas/              Strict shared input and output contracts
  services/property.ts  Validated calculations shared by both transports
  services/omanProperty.ts Deterministic Oman property-analysis pipeline (analyze_oman_property)
  middleware/auth.ts    API-key authentication
  middleware/rateLimit.ts In-memory, IP-keyed rate limiter for public agent endpoints
  billing/catalog.ts    Indicative prices and injectable authorization boundary (single source of truth)
  billing/service.ts    BillingService: the only place a price is read; usage recording
  billing/usage.ts      UsageRepository abstraction (Console/Memory/Postgres implementations)
  billing/x402.ts       Real x402 payment middleware + always-on x402 info builder
  config/env.ts         Validated environment configuration
  utils/                Safe errors and metadata-only logging
  mcp/server.ts         MCP registration factory (shared by both transports)
  mcp/remote.ts         Remote Streamable HTTP MCP handler (/mcp) + /api/v1/mcp/status builder
  mcp.ts                Local stdio entry point
  server.ts             HTTP listener and shutdown
  calculators.ts        Compatibility re-exports

Services validate direct calls as well as transport calls. New capabilities belong in the shared catalog with input/output schemas and a service function; the catalog drives REST, MCP and OpenAPI. No calculation logic lives in the HTTP or MCP handlers, and no pricing logic lives in the calculation services — every price is read through BillingService, which reads billing/catalog.ts.

Capability registry

src/domain/capabilities.ts exports one array, capabilities: AgentCapability[], and that array is the only place a tool's name, path, description, whenToUse/useCases (the recommendation-layer hint for which tool answers which situation), input/output schema, example, price, currency, payment protocol, idempotency and side-effect flag are written. Every consumer below reads this array rather than holding a second copy:

• REST route registration (api/app.ts) — both the X-API-Key and x402 route families
• The OpenAPI document (api/openapi.ts) — operationId is the capability's own name (analyze_property, compare_properties, estimate_maintenance, analyze_oman_property), and request/response examples come from capability.example/capability.execute(capability.example)
• The MCP server (mcp/server.ts) — tool name, schemas, and a description built from capability.description + capability.whenToUse
• The x402 payment gate and BillingService (billing/x402.ts, billing/service.ts) — billing/catalog.ts's prices object is derived from capabilities (Object.fromEntries(capabilities.map(c => [c.name, c.price]))), never a second literal
• Every agent-marketplace/discovery endpoint (/api/v1/agent, /api/v1/pricing, /api/v1/tools, /api/v1/capabilities, /agent.json, the two /.well-known/... manifests, /llms.txt)

Adding a capability to this one array is what makes it real everywhere at once; nothing else needs to be told about it separately. src/domain/roadmap.ts holds a separate, much smaller list (plannedCapabilities) of future tools — estimate_property_rent, analyze_lease, check_contract_risk, diagnose_maintenance_issue, estimate_repair_cost, generate_property_report — that are metadata only: no route, no MCP registration, no schema, no price, nothing callable. They exist so /agent.json and /llms.txt can tell an agent what's coming without it mistaking a name on a list for a working endpoint; promoting one to a real capability means adding a full entry to capabilities, the only registry that drives actual behavior (analyze_oman_property was itself on this list until this phase; it now has a full entry and has been removed from plannedCapabilities).

REST API

REST base: http://localhost:8787.

Method	Endpoint	Auth
GET	/	Public — HTML landing page (browsers) or JSON discovery (Accept: application/json)
GET	/agent.json	Public — full agent manifest (protocols, x402 terms, complete tool catalog)
GET	/.well-known/ai-plugin.json	Public — OpenAI-plugin-style manifest
GET	/.well-known/agent.json	Public — A2A-style Agent Card
GET	/llms.txt	Public — plain-text briefing for LLM-based agents (text/plain)
GET	/api/v1/capabilities	Public — machine-first capability registry (schemas, pricing, when to use)
GET	/api/v1/agent	Public — legacy agent-marketplace metadata (superseded by /agent.json)
GET	/api/v1/pricing	Public — full pay-per-call price list
GET	/api/v1/tools	Public — legacy tool catalog (superseded by /api/v1/capabilities)
GET	/api/v1/x402	Public — x402 protocol/pricing info (always available, independent of X402_ENABLED)
GET	/api/v1/x402/status	Public — factual runtime status: enabled, mode, network, asset, facilitator, walletConfigured, paymentEnforcement
POST	/api/v1/property/analyze	X-API-Key
POST	/api/v1/property/compare	X-API-Key
POST	/api/v1/maintenance/estimate	X-API-Key
POST	/api/v1/oman/property/analyze	X-API-Key
GET	/api/v1/health	Public liveness
GET	/openapi.json	Public raw OpenAPI document
POST	/api/v1/market-data/import	X-Partner-Token (Partner Data Feed — infrastructure, not an agent capability; see below)
GET	/api/v1/internal/market-data/status	X-Internal-Api-Key (Partner Data Feed; see below)
GET	/api/v1/internal/market-data/partners	X-Internal-Api-Key (Partner Data Feed; see below)

Legacy /v1/... POST routes and /health remain available. Response migration: legacy routes now return the same envelope as canonical routes; read results from response.data. Unknown fields are rejected, names must be unique after trimming, and unauthenticated startup is no longer allowed.

Success:

{
  "success": true,
  "data": {},
  "meta": { "requestId": "server-generated-uuid" }
}

A tool call (the four POST capabilities, on either the API-key or x402 route family) additionally enriches meta with the tool name, its price and its currency, so an agent can confirm what it was charged without a second lookup:

{
  "success": true,
  "data": { "grossYield": 8.47 },
  "meta": { "requestId": "server-generated-uuid", "tool": "analyze_property", "price": 0.01, "currency": "USD" }
}

Error:

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Input validation failed",
    "details": [{ "path": "propertyValue", "message": "Property value must be at least 0.01" }]
  },
  "meta": { "requestId": "server-generated-uuid" }
}

Responses include X-Request-ID. Codes cover 400 validation/malformed JSON, 401 authentication, 404 unknown endpoints, 413 bodies over 32kb, 415 unsupported content type/encoding, 500 sanitized internal failures, and 429 for a configured rate-limit adapter. PostgreSQL mode enforces customer minute limits and monthly quotas; env-key development mode has no default limiter. /openapi.json intentionally returns the raw specification for discovery tools.

Agent discovery, pricing and tool catalog

curl -s https://api.rafidsystem.com/api/v1/agent

{
  "success": true,
  "data": {
    "name": "Rafid Property Intelligence",
    "description": "Property and facility intelligence tools for AI agents",
    "version": "0.1.0",
    "mcp": true,
    "docs": "/docs",
    "openapi": "/openapi.json",
    "health": "/api/v1/health",
    "pricing": "/api/v1/pricing",
    "tools": "/api/v1/tools",
    "x402": "/api/v1/x402",
    "x402Enabled": false,
    "endpoints": ["/api/v1/property/analyze", "/api/v1/property/compare", "/api/v1/maintenance/estimate", "/api/v1/oman/property/analyze"]
  },
  "meta": { "requestId": "..." }
}

GET /api/v1/pricing returns { "currency": "USD", "model": "pay-per-call", "tools": { "analyze_property": 0.01, "compare_properties": 0.03, "estimate_maintenance": 0.02, "analyze_oman_property": 0.25 } } — the exact same object billing/catalog.ts defines, with nothing recomputed or duplicated. GET /api/v1/tools returns one entry per capability with a full JSON Schema for its input and a derived output summary, enough for an agent to construct a valid call without reading any documentation.

Landing page