# auth.md

How an autonomous agent obtains access to mdapi.io and keeps it.

There are no accounts and no sign-up. Access is a bearer token issued against a payment, and a request that needs one is told so by the service itself rather than by this document.

## Discover

- https://mdapi.io/.well-known/ai-discovery.json - every protocol, endpoint and capability in one document.
- https://mdapi.io/.well-known/x402.json - the payment manifest: networks, assets, receiving addresses and the scheme each rail speaks.
- https://mdapi.io/.well-known/skill.md - the conversion skill as an agent reads it.

## Pick a method

1. **Automatic.** The agent pays and the service activates a token in the same exchange (x402).
2. **Prepaid token.** A token is obtained once against a payment and reused; its balance is drawn down per conversion.
3. **Human-in-the-loop.** The service returns payment details and a QR code, a human pays, and the agent resumes.

All three end in the same credential and the same header.

## Register

There is no registration step. The first request for work that is paid answers `402`, and that answer carries what is needed to pay: the amount, the network, the receiving address, the reference and a QR code.

## Pay

Send the asset named in the `402` answer to the address it names, on the network it names, carrying the reference it names. The reference is what ties a payment to a request: a payment that does not carry it cannot be matched to the request that asked for it.

## Exchange the assertion

Repeat the same request with the credential the `402` answer issued:

- `Authorization: Bearer <token>`
- `X-MDAPI-Memo-Required: <memo>` until the token is activated

Once the payment is seen the token is activated and the request answers `200`. From then on the token alone is enough.

## Use the access token

Send `Authorization: Bearer <token>` on any request that needs paid work. min $0.01 per conversion (USDC via x402); a wider `capacity` step is charged the price of its own window. To refill, pay again with a memo and repeat a request naming the same token - the amount is added to its balance and a fresh year starts from the payment.

## Errors

| Status | Meaning |
| --- | --- |
| `402` | Payment required, or the credential presented is unknown or expired. The answer carries what to pay. |
| `401` | The credential presented is not valid for this endpoint. |
| `429` | The request rate for this caller is exhausted. |

## Revocation

`POST /token` rotates, revokes or recovers a token account. The right to do so is proven by a transaction on the paying wallet, never by the bearer alone.

## Links

- **About service:** https://mdapi.io/about
- **Privacy:** https://mdapi.io/privacy
- **Contact:** https://mdapi.io/contact
- **Agent entry point:** https://mdapi.io/AGENTS.md or https://mdapi.io/agents.md or https://mdapi.io/agent.md
- **Agent access:** https://mdapi.io/auth.md
- **API documentation and conversion:** https://mdapi.io
- **MCP server manifest:** https://mdapi.io/mcp
- **Health check:** https://mdapi.io/health
- **Documentation index:** https://mdapi.io/llms.txt
- **Full API documentation:** https://mdapi.io/llms-full.txt
- **AI discovery:** https://mdapi.io/.well-known/ai-discovery.json or https://mdapi.io/ai-discovery.json
- **AI Agent discovery:** https://mdapi.io/.well-known/agent.json or https://mdapi.io/agent.json
- **A2A Agent card:** https://mdapi.io/.well-known/agent-card.json or https://mdapi.io/agent-card.json
- **ACP manifest:** https://mdapi.io/.well-known/acp.json or https://mdapi.io/acp.json
- **x402 payment manifest:** https://mdapi.io/.well-known/x402.json or https://mdapi.io/x402.json or https://mdapi.io/.well-known/x402
- **OpenAPI specification (JSON):** https://mdapi.io/.well-known/openapi.json or https://mdapi.io/openapi.json
- **OpenAPI specification (YAML):** https://mdapi.io/.well-known/openapi.yaml or https://mdapi.io/openapi.yaml
- **MAPI specification:** https://mdapi.io/.well-known/mapi.md or https://mdapi.io/mapi.md
- **Skill specification:** https://mdapi.io/.well-known/skill.md or https://mdapi.io/skill.md
- **ARD manifest:** https://mdapi.io/.well-known/ard.json or https://mdapi.io/.well-known/ai-catalog.json or https://mdapi.io/ard.json
- **Agent Plugins manifest:** https://mdapi.io/.well-known/plugin/plugin.json or https://mdapi.io/.well-known/plugin.json
- **Agent Plugins MCP config:** https://mdapi.io/.well-known/plugin/mcp.json
- **Agent Plugins conversion skill:** https://mdapi.io/.well-known/plugin/skills/mdapi-conversion/SKILL.md
- **API documentation pages:** https://mdapi.io/docs
- **Example pages:** https://mdapi.io/docs/examples

## External Links

- **github.com** https://github.com/mdapiio/mdapi.io
- **skills.sh** https://www.skills.sh/mdapiio/mdapi.io
- **skillsmp.com** https://skillsmp.com/creators/mdapiio/mdapi.io
- **clawhub.ai** https://clawhub.ai/mdapiio
- **x.com** https://x.com/mdapiio

## Disclaimer

**The service is provided "AS IS".**


> mdapi.io is an edge-native service-transport primitive for AI, autonomous agents, and the Web4 ecosystem.
