Agent readiness
How safely an autonomous agent can discover, authenticate (via x402), call, and recover from errors on this API — scored against the agent-readiness dimension model.
Audience: Agent developers, marketplace integrators (Poncho, pay.sh, MPPscan), and procurement teams evaluating x402 APIs.
Not marketing fluff: Each signal is observable from public URLs — OpenAPI, well-known discovery, response headers, and npm audit scripts in this repo.
What Concierge exposes
| Signal | URL / header | Role |
|---|---|---|
| OpenAPI 3.1 | GET /openapi.json | Canonical contract — info.x-guidance, x-payment-info, components.securitySchemes, examples on every operation |
| RFC 9727 catalog | GET /.well-known/api-catalog | Linkset index — OpenAPI, MCP, x402, agent card, AsyncAPI stub |
| x402 fan-out | GET /.well-known/x402 | Paid route list + ownership proofs for x402scan / Bazaar |
| Agent card | GET /.well-known/agent-card.json | ERC-8004-style A2A discovery |
| MCP HTTP | GET /api/mcp | JSON-RPC tools/list · tools/call for intel routes |
| Official MCP Registry | xyz.conc-exe/concierge-intel | Published v1.0.1 — integration guide |
| AsyncAPI stub | GET /asyncapi.json | Event contract placeholder (HTTP-only today; webhooks reserved) |
| LLM index | GET /llms.txt | Human + agent doc map |
| Rate-limit policy | X-RateLimit-Limit, RateLimit-Limit | 120 req/min soft limit on /api/* — documented in OpenAPI 429 responses |
| Idempotency | Idempotency-Key header | Optional on POST; reuse PAYMENT-SIGNATURE after settlement to avoid double-pay |
| Agent attribution | X-Agent-Id: agt_… | Registered agent identity — see Agent Identity |
| Consent | GET /robots.txt | Content-signal: search=yes, ai-input=yes, ai-train=no |
Twelve audit dimensions
Repo script npm run agent-readiness:audit scores 0–3 per dimension (mean across core + forward-looking):
| Dimension | Concierge posture |
|---|---|
| Spec presence | OpenAPI 3.1 at predictable URL, static + live |
| Auth model clarity | x402Payment security scheme + x-payment-info per route |
| Idempotency | Idempotency-Key documented; payment signature dedup guidance in info.x-guidance |
| Error semantics | components.schemas.ApiError — stable code enum; 400/402/429/500 on all paid ops |
| Rate-limit headers | X-RateLimit-* on API responses; Retry-After on 429 in spec |
| Dry-run / simulate | GET intel probes → 402; POST /api/token-pay-preview; playground |
| OpenAPI examples | operationId, request + response examples on every operation |
| MCP server | First-party HTTP MCP at /api/mcp |
| AsyncAPI / events | Stub at /asyncapi.json (no live webhooks yet) |
| RFC 9727 api-catalog | /.well-known/api-catalog linkset+json |
| Consent signals | Content-signal in robots.txt |
| Web Bot Auth | Signature-Agent header → agent identity docs |
Verify (integrators & CI)
# Live production audit (all dimensions incl. headers + MCP)
npm run agent-readiness:audit
# JSON output for CI
node scripts/audit-agent-readiness.mjs --json
# Local — OpenAPI + static discovery files (no live probes)
npm run agent-readiness:local
# Related discovery checks
npm run discovery:validate
curl -s https://conc-exe.xyz/.well-known/api-catalog | jq '.linkset | length'
curl -sI https://conc-exe.xyz/api/concierge-intel-tvl -X POST | grep -i ratelimitClone api-evangelist/agent-readiness for the rubric. Concierge audit script: scripts/audit-agent-readiness.mjs.
Distribution (phase 2)
Ship metadata in-repo; publish to external registries with the commands below.
| Channel | Status | Command / path |
|---|---|---|
| MCP Registry | Published | xyz.conc-exe/concierge-intel v1.0.1 · guide |
thebuyside pay.discover | PR open | PR #2 · npm run distribution:thebuyside-pr |
| pay.sh / pay-skills | Bundle in repo | npm run distribution:paysh-pr — prepare pay-skills provider PR |
| Agent Skill (SKILL.md) | Published | /skills/concierge-intel/SKILL.md |
| CI quality gate | GitHub Actions | .github/workflows/discovery-quality.yml |
Related pages
API Overview
Base URL, discovery table, CORS
For Builders
Integration paths — OpenAPI, AgentCash, pay.sh
Discover UI
Live x402 fan-out, MCP, agent card probes
MCP Registry
Official listing — streamable HTTP at /api/mcp
Agent Card
A2A registry and agt_ identities
Concierge · Executive Lounge