Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: AgentLedger .well Known API
version: 0.4.7
x-guidance: 'AgentLedger is per-agent AI spend tracking with ENFORCED budget caps. Two ways in, both machine-only. (1) FREE, no wallet: POST /start mints a workspace_key (shown once) with no signup and no card — GET /start only renders the form and does NOT mint. Claim an agent with the key in the body of POST /v1/track, set a cap with POST /v1/budget, then route traffic through /proxy/{provider}/... so an over-budget call is refused with 402 BEFORE the provider is contacted. (2) PAID, no human: POST /v1/billing/x402 with a wallet-signed x402 payment mints a workspace bound to the paying wallet. NOTE: a workspace_key claims NEW agents; an agent_secret writes to an existing one. Plain POST /v1/track can reject the ledger write that would cross a cap but cannot un-spend a charge that already happened — only the proxy/wrapper path stops money.'
tags:
- name: .well Known
paths:
/.well-known/glama.json:
get:
summary: Glama Claim
description: Glama HTTP-challenge ownership verification file.
operationId: glama_claim__well_known_glama_json_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/mcp/server-card.json:
get:
summary: Mcp Server Card
description: 'Static MCP server card (SEP-1649 shape).
Read from the committed server-card.json, which is itself generated from a
captured tools/list and then checked into the repo. It is therefore a
snapshot, NOT computed per request — if the served tools change, regenerate
the file. (An earlier version of this docstring said "generated from the live
tools/list", which implied a freshness this route does not have.) Directory
scanners that cannot complete an automated scan (auth wall, WAF, bot rules)
read this path when scanning is blocked.'
operationId: mcp_server_card__well_known_mcp_server_card_json_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/personal-agent.json:
get:
summary: Personal Agent Discovery
description: 'Personal Agent Protocol discovery document (v0.1-shaped, PROVISIONAL).
PROVISIONAL — HONESTY NOTE. PAP was announced 2026-10-06 and its v0.1
specification is NOT published. Sierra''s announcement domain
(personalagentprotocol.com) still returns HTTP 401, and no spec repo,
licence or governance exists. The field names below are therefore a
best-effort reading of the announcement''s prose, NOT a conformance claim.
The `paper_spec_published` field reports this machine-readably so no
consumer mistakes this for an implemented standard.
What IS real here: the discovery shape itself. PAP states a personal
agent "starts on the website, where it can discover what the company
offers and how to reach it" — and this file serves exactly that, from the
same data as /v1/products. When PAP v0.1 lands, this is the one file that
needs remapping; nothing else in the city depends on the field names.'
operationId: personal_agent_discovery__well_known_personal_agent_json_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/agent.json:
get:
summary: Agent Json
description: 'AEO capability manifest: agents discover what this product does,
pricing, auth, and how to call it (rules/agent-native-standard.md).'
operationId: agent_json__well_known_agent_json_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/agent-card.json:
get:
summary: Agent Card Json
description: 'Alias of /.well-known/agent.json.
Agents request this spelling 136 times in the live log (2026-09-14) and got
a 404 every time. `agent-card.json` is the name used by several crawler
families. Serving the same manifest under every spelling an agent actually
asks for beats making them learn ours. Same content, no second source of
truth: this returns AGENT_JSON, it does not copy it.'
operationId: agent_card_json__well_known_agent_card_json_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/mcp.json:
get:
summary: Mcp Wellknown Json
description: 'City-wide MCP catalog: all six MCP servers, true tool lists.
Distinct from /.well-known/mcp/server-card.json (which is the richer
registry card for AgentLedger alone). Tool names and counts live in
CITY_CATALOG (one source of truth, shared with /v1/products and the
Personal Agent Protocol discovery document). The satellite servers'' native
MCP tool dispatch was timing out server-side when the gateway translation
was introduced; re-probed 2026-10-07 it completes on all four, so the
translation is now a fast path. The city gateway translates their tool calls to the
documented REST APIs, so they are listed as live with an honest status
note rather than hidden.'
operationId: mcp_wellknown_json__well_known_mcp_json_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/agent-directory.json:
get:
summary: Agents Directory Aliases
description: 'Every spelling of the agent manifest that live crawlers actually request.
Counted in /data/metrics.jsonl (2026-09-15): /.well-known/agents.json 30x,
/.well-known/agent-directory.json 28x, /agent-directory.json 28x,
/agents.json 22x — all 404. There is no directory concept here, so the honest
answer is the capability manifest. Returning AGENT_JSON (the single source of
truth) beats inventing a second document that could drift from it.'
operationId: agents_directory_aliases__well_known_agent_directory_json_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/agents.json:
get:
summary: Agents Directory Aliases
description: 'Every spelling of the agent manifest that live crawlers actually request.
Counted in /data/metrics.jsonl (2026-09-15): /.well-known/agents.json 30x,
/.well-known/agent-directory.json 28x, /agent-directory.json 28x,
/agents.json 22x — all 404. There is no directory concept here, so the honest
answer is the capability manifest. Returning AGENT_JSON (the single source of
truth) beats inventing a second document that could drift from it.'
operationId: agents_directory_aliases__well_known_agents_json_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/mcp:
get:
summary: Mcp Manifest Aliases
description: 'Bare-manifest spellings for the MCP descriptor.
/.well-known/mcp 29x and /mcp.json 29x in the live log, both 404. Delegates to
the existing /.well-known/mcp.json handler so there is one implementation.'
operationId: mcp_manifest_aliases__well_known_mcp_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/oauth-authorization-server/mcp:
get:
summary: Oauth Discovery Absent
description: 'Answer the OAuth discovery probes honestly, instead of 404ing them.
An MCP client that wants authenticated transport walks RFC 9728 / RFC 8414
discovery before it will connect. Measured 2026-09-16 in /data/metrics.jsonl:
150 such probes 404''d, including /mcp/-relative variants. A 404 reads as
"discovery is broken"; it does not read as "no auth here".
This deployment has no auth layer at all — MCP here is deliberately open
(`claude mcp add --transport http agent-ledger https://aiagentscity.com/mcp/`
needs no login). The correct answer is therefore an explicit empty discovery
document: it tells the client no authorization server exists, so it should
proceed unauthenticated, and it stops the 404 loop.
Returning a fake authorization_server here would be worse than the 404: it
would send a client to an endpoint that cannot issue tokens.'
operationId: oauth_discovery_absent__well_known_oauth_authorization_server_mcp_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/oauth-authorization-server:
get:
summary: Oauth Discovery Absent
description: 'Answer the OAuth discovery probes honestly, instead of 404ing them.
An MCP client that wants authenticated transport walks RFC 9728 / RFC 8414
discovery before it will connect. Measured 2026-09-16 in /data/metrics.jsonl:
150 such probes 404''d, including /mcp/-relative variants. A 404 reads as
"discovery is broken"; it does not read as "no auth here".
This deployment has no auth layer at all — MCP here is deliberately open
(`claude mcp add --transport http agent-ledger https://aiagentscity.com/mcp/`
needs no login). The correct answer is therefore an explicit empty discovery
document: it tells the client no authorization server exists, so it should
proceed unauthenticated, and it stops the 404 loop.
Returning a fake authorization_server here would be worse than the 404: it
would send a client to an endpoint that cannot issue tokens.'
operationId: oauth_discovery_absent__well_known_oauth_authorization_server_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/oauth-protected-resource/mcp:
get:
summary: Oauth Discovery Absent
description: 'Answer the OAuth discovery probes honestly, instead of 404ing them.
An MCP client that wants authenticated transport walks RFC 9728 / RFC 8414
discovery before it will connect. Measured 2026-09-16 in /data/metrics.jsonl:
150 such probes 404''d, including /mcp/-relative variants. A 404 reads as
"discovery is broken"; it does not read as "no auth here".
This deployment has no auth layer at all — MCP here is deliberately open
(`claude mcp add --transport http agent-ledger https://aiagentscity.com/mcp/`
needs no login). The correct answer is therefore an explicit empty discovery
document: it tells the client no authorization server exists, so it should
proceed unauthenticated, and it stops the 404 loop.
Returning a fake authorization_server here would be worse than the 404: it
would send a client to an endpoint that cannot issue tokens.'
operationId: oauth_discovery_absent__well_known_oauth_protected_resource_mcp_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/oauth-protected-resource:
get:
summary: Oauth Discovery Absent
description: 'Answer the OAuth discovery probes honestly, instead of 404ing them.
An MCP client that wants authenticated transport walks RFC 9728 / RFC 8414
discovery before it will connect. Measured 2026-09-16 in /data/metrics.jsonl:
150 such probes 404''d, including /mcp/-relative variants. A 404 reads as
"discovery is broken"; it does not read as "no auth here".
This deployment has no auth layer at all — MCP here is deliberately open
(`claude mcp add --transport http agent-ledger https://aiagentscity.com/mcp/`
needs no login). The correct answer is therefore an explicit empty discovery
document: it tells the client no authorization server exists, so it should
proceed unauthenticated, and it stops the 404 loop.
Returning a fake authorization_server here would be worse than the 404: it
would send a client to an endpoint that cannot issue tokens.'
operationId: oauth_discovery_absent__well_known_oauth_protected_resource_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/x402.json:
get:
summary: X402 Wellknown Json
description: 'The till, published where agents actually look.
An agent with 1,343 successful MCP calls (`b628ad13e37e`) probed
/.well-known/x402, /payments, /pricing, /payment and /monetization on
2026-09-14 and every one returned 404. It was looking for how to pay us
and we told it nothing. This is the signpost.
Values are read from the same env the verifier uses, so this cannot drift
from what the endpoint actually charges.
Served at BOTH spellings deliberately. x402scan''s own spec says it fetches
`/.well-known/x402` (no extension) first and falls back to `.json`, and its
`registerFromOrigin` is documented to fail with `noDiscovery` if only one
variant is served. They are one function, so they cannot disagree.'
operationId: x402_wellknown_json__well_known_x402_json_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/x402:
get:
summary: X402 Wellknown Json
description: 'The till, published where agents actually look.
An agent with 1,343 successful MCP calls (`b628ad13e37e`) probed
/.well-known/x402, /payments, /pricing, /payment and /monetization on
2026-09-14 and every one returned 404. It was looking for how to pay us
and we told it nothing. This is the signpost.
Values are read from the same env the verifier uses, so this cannot drift
from what the endpoint actually charges.
Served at BOTH spellings deliberately. x402scan''s own spec says it fetches
`/.well-known/x402` (no extension) first and falls back to `.json`, and its
`registerFromOrigin` is documented to fail with `noDiscovery` if only one
variant is served. They are one function, so they cannot disagree.'
operationId: x402_wellknown_json__well_known_x402_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
/.well-known/payments:
get:
summary: Payments Wellknown Json
description: Alias for the payment discovery document (agents probe both spellings).
operationId: payments_wellknown_json__well_known_payments_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
tags:
- .well Known
x-service-info:
docs:
llms: /llms.txt
x-products:
- id: trustscan
x-slot: trust
x-direction: outward
x-connect:
mcp: https://aiagentscity.com/mcp/trustscan
paid_call: POST https://aiagentscity.com/api/x402/trustscan/npm
human: https://aiagentscity.com/trust-scan
tagline: Scan before you trust
free_proof: POST /api/trustscan/npm returns registry facts + a typosquat screen for any package, unauthenticated — the same check is payable per call over x402 without the rate limit; remote deep scans are path-scoped to the host
- id: agent-watch
x-slot: trust
x-direction: outward
x-connect:
mcp: https://aiagentscity.com/mcp/agent-watch
paid_call: POST https://aiagentscity.com/api/x402/agent-watch/probe
human: https://aiagentscity.com/agent-watch
tagline: Is this agent or MCP server real and still behaving?
free_proof: aw_health + aw_census MCP tools are open reads — live census data, no auth
- id: perimeter-watch
x-slot: trust
x-direction: outward
x-connect:
mcp: https://aiagentscity.com/mcp/perimeter-watch
human: https://aiagentscity.com/perimeter-watch
tagline: Is your endpoint still what it claims — checked from the outside?
free_proof: free browser snapshot — https://entradox.github.io/perimeter-watch-site/
- id: benefits-city
x-slot: outcome
x-direction: outward
x-connect:
mcp: https://aiagentscity.com/benefits/mcp
human: https://aiagentscity.com/benefits
tagline: Verified offer records — will this action actually pay?
free_proof: search_bonuses / get_bonus MCP tools return hand-verified records with source URLs — no auth
- id: cited
x-slot: outcome
x-direction: outward
x-connect:
mcp: https://aiagentscity.com/mcp/cited
human: https://aiagentscity.com/cited
tagline: Prove the claim that AI recommends you — verbatim evidence
free_proof: free browser scan — https://entradox.github.io/cited-site/
- id: agent-ledger
x-slot: outcome
x-direction: spine
x-connect:
mcp: https://aiagentscity.com/mcp/
rest: https://aiagentscity.com/v1/
install: npx @aiagentscity/setup ledger
human: https://aiagentscity.com/agent-ledger
tagline: Metered, capped, receipted agent spend — proof of what every cent bought
free_proof: POST /start mints a free workspace (3 agents, every rail) — no signup, no card
- id: workbench-kit
x-slot: trust+outcome
x-direction: inward
x-connect:
install: npx @aiagentscity/setup workbench
human: https://aiagentscity.com/workbench
tagline: Frame, gate, and close-receipt every agent task — proof of what your agents did
free_proof: the whole kit is free and runs fully offline — `wb verify <receipt_id>` recomputes a close receipt against the local ledger
x-frame:
frame: trust-and-outcome
tagline: 'The trust-and-outcome clearing layer for the agent economy: before an agent acts, it verifies the counterparty; after it acts, it proves the result.'
questions:
trust: Before an agent acts — can it trust the counterparty?
outcome: After an agent acts — did it work?
directions:
outward: verifies counterparties outside your fleet
spine: the receipts rail every instrument writes through
inward: verifies your own fleet's work
parked: []