aefi

HTTP API

Base URL: https://api.aefi.io. JSON in, envelope out. CORS allows aefi.io and demo.aefi.io.

Auth

Agents pay 0.01 USDC per call (x402 + MPP) on /v1/* except /v1/scenarios. Unpaid calls return 402 with an accepts[] body, PAYMENT-REQUIRED, and WWW-Authenticate: Payment. Retry with PAYMENT-SIGNATURE. Humans and Evidence Studio may send x-aefi-api-key instead.

Machine-readable spec (free): GET https://api.aefi.io/openapi.json. Contact: [email protected].

Accepts Agent Payments

Endpoints

Method Path Purpose
GET /health Liveness + Neo4j connectivity
POST /v1/providers/search Provider search (NL + filters + sort/page)
GET /v1/providers/:id Single provider performance envelope
GET /v1/transactions/:hash Explain transaction
POST /v1/payments/verify Verify by tx_hash or payment_id
GET /v1/jobs/:job_id ERC-8183 job lookup
GET /v1/agents/:id/activity Observed activity (partial)
GET /v1/scenarios Studio search presets
POST /v1/authority/check Wave B — honest gap envelope
GET /v1/tasks/:id Wave C — honest gap envelope

Search body

{
  "query": "string, optional",
  "capability": "optional exact tag",
  "minimum_verified_jobs": 0,
  "minimum_completion_rate": 0,
  "minimum_confidence": "unverified",
  "sort_by": "score",
  "sort_dir": "desc",
  "limit": 25,
  "offset": 0,
  "semantic_top_k": 20
}

result includes results, total_matched, offset, limit, sort_by, sort_dir, has_more.

Verify body

{
  "tx_hash": "0x…",
  "payment_id": "pay:5042002:0x…:13"
}

Send one identifier. payment_id is the faster unique lookup.

Errors

Transport errors are HTTP status. “Not in graph” is still 200 with verified: false or found: false and coverage gaps — absence is a first-class result.