API reference

Discover, inspect and integrate

AI discovery

POST /api/discover
Content-Type: application/json

{"request":"Find an agent for weather forecasts and air quality","chain":"all"}

request accepts 15–500 characters; use English. chain is all (default), sepolia, arbitrum or arc. DeepSeek ranks published candidates. The response includes request, matches, conclusion, searched, considered, generatedAt, model and registry. registry contains status (live, partial, stale, unavailable or not_applicable), indexedBlock, indexedAt, checked, eligible and withheld candidate reasons. A Graph failure may return HTTP 200 with zero recommendations on the affected network and an explicit unavailable/stale status; it is not a successful recommendation. Each match contains key, chain, agentId, name, description, reason, evidenceQuote, gaps, category and serviceCount. Sepolia and Arc matches also contain registryEvidence (pinned current block, snapshot baseline block, owner, historical counters and server-derived signals) and registrySignals (IDs selected by the AI). Only fresh evidence with matching ownership and metadata URI passes. An empty matches array is a valid no-match result. The compatibility brief field contains extracted requirements and search terms; its former narrative fields are empty.

Reasons are limited to 180 characters. Each exact description quote is 12–300 characters, with at most two unknowns of 120 characters each. The conclusion is a fixed interface message, not a generated essay. These limits concern model output, not the 500-character user request.

Errors: 400 invalid input, 403 cross-origin rejection, 413 oversized body, 429 throttling/provider quota, 503 generation or provider failure. Searches share a 45-second deadline; client integrations should allow for this latency. Results are not cached. Throttling is per instance, not a global spending cap.

Current evidence

POST /api/evaluate
Content-Type: application/json

{"chain":"sepolia","agentId":1194,"job":"custom","request":"Weather forecasts and air quality"}

Use custom with the original task, or wallet_report, research or payments. Responses include decision, checks, services, checkedAt, expiresAt, owner, block, metadataHash and fingerprint. Service observations report URL, status, protocol, HTTP status when available and latency. automaticExecutionAllowed is always false. Reports expire after 15 minutes. See the trial workflow for manual reviews and their limits.

Complaint publication records

GET /api/complaints?chain=sepolia&agentId=10226&status=all&page=1

Filters: chain (sepolia, arbitrum or arc), agentId, author wallet and status (all, open, resolved or flagged). Returns at most 20 published records per page, open/resolved/flagged counts excluding demo records, and fee configuration. Use id for a detail and eventPage for its signed history (20 events per page). Pending drafts are not public. Unavailable storage returns 503 rather than empty statistics.

POST /api/complaints

Send action and signature. The strict action schemas and exact consent message are defined in lib/complaints.ts. Sign complaintMessage(action); timestamps expire after 15 minutes. Actions: prepare (signed structured draft), publish (draft ID and payment transaction on the reserved network), edit (new fields), reply (provider response) and status (open/resolved with explanation). Edits, replies and status changes include the current record version, preventing stale updates and signature replay. Initial publication is idempotent.

New drafts set paymentVersion: 2 and pay exactly 5 test USDC on their agent network: Sepolia (11155111), Arbitrum Sepolia (421614), or Arc Testnet (5042002). Sepolia and Arbitrum use Circle USDC ERC-20 transfers (6 decimals); gas requires test ETH. Arc uses native USDC (18 decimals). complaintTransaction(draft) builds the exact transaction: ERC-20 transfer(treasury, 5000000) calldata followed by the 32-byte complaintCommitment, or native value plus that commitment. The server verifies chain, sender, destination, amount, exact calldata, successful canonical inclusion and, for ERC-20, a matching Transfer event from the configured token. No allowance is requested. GET responses include fee.networks with token addresses and explorer URLs. Existing drafts without paymentVersion retain their original Arc payment and commitment, even when the agent is on another network. Author contract-wallet signatures are checked on the reserved payment network; provider signatures and current ownership are checked on the agent network. Signed edits remain in the versioned database history.

Errors: 400 malformed fields, 401 expired/invalid signature, 403 wrong actor or origin, 404 missing published record, 409 version conflict or update limit, 413 oversized body, 422 mismatched payment and 503 unavailable RPC/storage. Requests are bounded to 32 KB; updates are limited to ten signed events per actor per minute. Reuse the original payment hash after a storage failure; never charge again merely to retry publication.

Archived ratings

GET /api/reviews?chain=sepolia&agentId=1194

Historical reviews and their evidence downloads remain read-only. POST /api/reviews now returns 410 and directs clients to Orders. Existing ratings are not converted into paid complaints or purchase verification.

Arbitrum evaluation history

GET /api/evaluations?chain=arbitrum&agentId=205

Reads EvaluationRecorded events from the live NomenEvaluationRegistry deployment on Arbitrum Sepolia. The response includes individual hash-only receipts and totals for passed, failed and inconclusive outcomes plus distinct reviewer wallets. A wallet count is not a person count or proof of independent users. An RPC failure returns 503 with status unavailable; it is never converted as zero reviews.

Indexed registry activity

GET /api/activity?chain=sepolia&agentId=10226

Reads the selected network from The Graph; chain accepts sepolia or arc. Arc covers the 249 explicitly listed catalog IDs, not all registered agents. The discovery registry.networks array reports status, scope and block independently for each requested supported network. The response includes indexedBlock, freshness and indexed agent events. Missing records may not have been indexed yet. A stale flag means the indexed block is over 15 minutes old or its timestamp is unknown. Indexed name events do not establish current endorsement; call registrar.isNamed. Errors: 400 unsupported chain or invalid ID, 503 no configured endpoint, 502 unavailable index.

Snapshot verification

The API exists for callers that are themselves agents. It answers which of the six checks a record passed or failed and why, and lets the caller decide. It never says “trustworthy”.

Request

GET /api/snapshot?chain=<ethereum|sepolia|arbitrum|arc>&agentId=<id>

Results use published scan data and include provenance. This endpoint has no NOMEN payment requirement. A snapshot lookup is not a fresh service or task-performance check.

Response

Field	Meaning
`status`	One of `passes`, `no_metadata_uri`, `metadata_unreachable`, `metadata_not_json`, `required_field_missing`, `duplicate_of_earlier_record`, `no_describable_purpose`, `not_registered`, `not_scanned`, `rpc_error`. Unknown and failed reads are not evidence of absence.
`passes`	Boolean shortcut for `status == "passes"`.
`reason`	One sentence a human or a model can read.
`agent`	Present only when it passes: name, type, description, owner, endpoints, category, metadata source and hash, labels.
`scan`	Published snapshot provenance, coverage, scan timestamp when verified, pinned ownership block and counts. This is not a live metadata check.

Payment

/api/snapshot and POST /api/toplu are free. /api/dogrula serves the same snapshot and optionally demonstrates x402 v2 payments when NOMEN_PAY_TO is configured. That optional path uses Base Sepolia USDC; it is not an Arc integration or a premium live verification service. A real 0.001 test USDC payment through the production endpoint was verified on September 11, 2026, including invalid-signature and replay rejection. See /x402-evidence.json for the transaction. The public testnet facilitator occasionally rejects settlement; a failed payment must not be treated as a successful lookup.

From an agent, in six lines

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const fetchPaid = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(privateKeyToAccount(KEY)) }],
});
const verdict = await (await fetchPaid(URL)).json();

Why an agent would call this

Before paying another agent for work, before routing a job to it, before quoting its identity to a user. The registry answers “does this id exist”; NOMEN answers “does this id mean anything”. Try it on the developers page.