Exchange-rate data forAI agents
Give your agent anonymous, claimable access to real-time Ethiopian bank exchange rates over a small, open protocol. No human account to start — discover the endpoints, fetch a token, and read the latest rates. Free by default.
How it works
The anonymous path mirrors OAuth 2.0 client credentials: an anonymous identity, an identity assertion exchanged for a Bearer token. An optional claim ceremony (like OAuth device authorization) lets a human bind their email to the agent. Every URL below is served by the API host you are configured against.
1 · Discover
Read the metadata
Fetch https://exchange-rate-aggregator-et.onrender.com/.well-known/oauth-authorization-server to learn the exact endpoints, grant types, and the AUTH.md recipe.
2 · Identify
Anonymous identity
POST https://exchange-rate-aggregator-et.onrender.com/api/v1/agent/identity. You get a signed identity_assertion (a short-lived JWT) for the token endpoint.
3 · Token
Get a Bearer token
POST https://exchange-rate-aggregator-et.onrender.com/api/v1/oauth2/token with the jwt-bearer grant to exchange your assertion for an access token.
4 · Claim (optional)
Link an email
Start a claim ceremony and print the user_code — a human confirms it at /agent/claim to own the agent.
Discover the protocol
Like an OAuth 2.0 authorization server, the API publishes its metadata at the RFC 8414 well-known location. Your agent should always read this document instead of hardcoding endpoints — it is the source of truth and may change.
curl https://exchange-rate-aggregator-et.onrender.com/.well-known/oauth-authorization-server
curl -s https://exchange-rate-aggregator-et.onrender.com/.well-known/oauth-authorization-server | jq .The metadata advertises:
token_endpoint— where to exchange an identity assertion or approved claim for a Bearer tokenagent_auth.identity_endpoint— where to resolve an anonymous identity or start a claim ceremonyagent_auth.claim_endpoint— where an agent starts a claim ceremony (the human confirms on this site at /agent/claim)service_documentation— the AUTH.md recipe (below)
{
"issuer": "exchange-rate-aggregator-et.onrender.com",
"token_endpoint": "https://exchange-rate-aggregator-et.onrender.com/api/v1/oauth2/token",
"revocation_endpoint": "https://exchange-rate-aggregator-et.onrender.com/api/v1/oauth2/revoke",
"agent_auth": {
"identity_endpoint": "https://exchange-rate-aggregator-et.onrender.com/api/v1/agent/identity",
"claim_endpoint": "https://exchange-rate-aggregator-et.onrender.com/api/v1/agent/identity/claim",
"identity_types_supported": ["anonymous", "service_auth", "identity_assertion"],
"events_supported": ["agent_registered", "agent_claimed", "credential_revoked"]
},
"service_documentation": "https://exchange-rate-aggregator-et.onrender.com/auth.md",
"scopes_supported": ["rates:read"],
"grant_types_supported": [
"urn:workos:agent-auth:grant-type:claim",
"urn:ietf:params:oauth:grant-type:jwt-bearer"
]
}The AUTH.md recipe
The API publishes AUTH.md — a plain Markdown document that agents can curl and follow step by step. It is the same flow documented on this page, but machine-friendly and kept in lockstep with the backend. Treat it as the canonical recipe.
Fetch the recipe from the service_documentation URL advertised in the metadata (currently https://exchange-rate-aggregator-et.onrender.com/auth.md), or follow the interactive flow below. The recipe works for both scripts and humans.
Fetch the recipe
curl -s https://exchange-rate-aggregator-et.onrender.com/auth.mdAnonymous quick start
Three calls and your agent can read real-time rates. No email, no API key dashboard — just an anonymous identity.
Create an anonymous identity
identity_assertion — a short-lived JWT your agent stores and presents at the token endpoint. The supported identity types are advertised by the discovery document.POST https://exchange-rate-aggregator-et.onrender.com/api/v1/agent/identity
curl -X POST https://exchange-rate-aggregator-et.onrender.com/api/v1/agent/identity \
-H 'Content-Type: application/json' \
-d '{"identity_type": "anonymous", "scope": "rates:read"}'{
"identity_type": "anonymous",
"identity_assertion": "eyJhbGciOiJIUzI1NiIs...",
"expires_in": 3600,
"issuer": "https://...",
"scope": "rates:read",
"token_endpoint": "https://exchange-rate-aggregator-et.onrender.com/api/v1/oauth2/token"
}Exchange for a Bearer token
POST https://exchange-rate-aggregator-et.onrender.com/api/v1/oauth2/token
curl -X POST https://exchange-rate-aggregator-et.onrender.com/api/v1/oauth2/token \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": "<identity_assertion>"
}'{
"access_token": "et_live_...",
"token_type": "Bearer",
"expires_in": 31536000,
"scope": "rates:read",
"tier": "free"
}The identity and token endpoints are rate-limited to 20 requests/hour per IP — cache the token and reuse it instead of minting one on every call.
Read the latest rates
Use the Bearer token
curl -s 'https://exchange.et/api/v1/latest-rates' \
-H 'Authorization: Bearer <access_token>' | jq .The claim ceremony
Agents are anonymous by default. When you want a person to own the agent — to manage it, recover it, or tie it to an account — that person claims it with the user code the agent prints.
1Agent starts a ceremony
Requesting a service_auth identity returns a short-lived user_code and a verification URL. The agent displays them:
Claim me at https://exchange.et/agent/claim?code=K7XQ-9MNP2Human confirms
The owner opens exchange.et/agent/claim, enters the code and their email, and confirms.
Go to the claim page3Agent mints its token
The user_code is valid for a short window (see the claim TTL in the metadata), so only the person holding it can claim the agent. After approval the agent exchanges its claim_token at the token endpoint (claim grant) to mint its access token.
Claiming is optional. An agent that is never claimed continues to work anonymously on the Free tier with no personal data attached.
Revocation
You can stop an agent at any time. Access tokens can be long-lived, so treat revocation as an active step rather than waiting for expiry.
Long-lived by default
expires_in (one year), so do not rely on expiry to cut off an agent. Your agent stores its identity assertion and can mint a fresh token whenever it needs one.Revoke before expiry
The discovery document advertises a revocation_endpoint (https://exchange-rate-aggregator-et.onrender.com/api/v1/oauth2/revoke). Call it with the access token to revoke immediately. Claimed agents can also be revoked from the owner's account. For anything else, email support@keydama.com with the agent's identity details.
Honest by default: Free tier first
- Free (default): real-time latest rates with a per-hour request budget — enough for most personal and evaluation agents.
- Pro, Growth, Enterprise: higher rate limits, full historical data, and currency conversion — see pricing for current tiers.
Frequently asked questions
Ready to connect your agent?
Your configured API host is exchange-rate-aggregator-et.onrender.com. Start at the metadata document or send your agent to the claim page.