# Server402 Agent Guide

Discover, choose, pay for, and call English-first paid APIs exposed by this Server402 marketplace via HTTP 402, x402 metadata, OpenAPI, and MCP.

Endpoints:
- openapi: https://aivps.lat/openapi.json
- mcp: https://aivps.lat/mcp
- discovery: https://aivps.lat/.well-known/server402.json
- apiCatalog: https://aivps.lat/.well-known/api-catalog
- audit: https://aivps.lat/api/discovery/audit
- catalog: https://aivps.lat/api/catalog
- search: https://aivps.lat/api/catalog/search
- openaiFunctions: https://aivps.lat/api/catalog/openai-functions.json
- payments: https://aivps.lat/api/payments
- apisJson: https://aivps.lat/apis.json
- llms: https://aivps.lat/llms.txt
- sitemap: https://aivps.lat/sitemap.xml

Workflow:
1. Read /.well-known/server402.json, /.well-known/api-catalog, /apis.json, or /llms.txt first.
2. Read /llms.txt when you need a concise natural-language overview for model context.
3. Use /api/catalog/search?q=your-task to find matching services.
4. Inspect service inputSchema, outputSchema, pricing, quality, and discovery.paymentFlow.
5. Call the service or MCP tool without a token to receive a 402 payment object, or create payment directly with POST /api/payments.
6. After payment is paid, retry with X-Payment-Token for HTTP or paymentToken for MCP.

Payment:
- Create payment: POST https://aivps.lat/api/payments
- Verify payment: GET https://aivps.lat/api/payments/{paymentId}
- HTTP token header: X-Payment-Token
- MCP token argument: paymentToken

Error Handling:
- HTTP 402 means payment is required, expired, pending, or exhausted; inspect the payment object and retry after status is paid.
- HTTP 401 means an API key is required or invalid.
- HTTP 403 means the API key is not allowed to use the requested service.
- HTTP 400 means the request does not match the service inputSchema.

Notes:
- Published and enabled services are visible to agents. Health checks are exposed as quality signals.
- Search results are ranked by text match, price, quality score, success rate, and latency.
- Search understands bilingual (English/Chinese) synonyms, so queries like "文字识别" match OCR services. Applied synonyms are returned in the response expandedTerms field.
- OpenAI-compatible clients can import every service as function-calling tools from /api/catalog/openai-functions.json; each tool carries x-server402 payment metadata.
- Quality metrics are derived from health checks and recent call logs.