{"schemaVersion":"server402.agent-guide.v1","name":"Server402 API Marketplace","purpose":"Discover, choose, pay for, and call English-first paid APIs exposed by this Server402 marketplace via HTTP 402, x402 metadata, OpenAPI, and MCP.","endpoints":{"apiCatalog":"https://x402vip.com/.well-known/api-catalog","apisJson":"https://x402vip.com/apis.json","audit":"https://x402vip.com/api/discovery/audit","catalog":"https://x402vip.com/api/catalog","discovery":"https://x402vip.com/.well-known/server402.json","llms":"https://x402vip.com/llms.txt","mcp":"https://x402vip.com/mcp","openaiFunctions":"https://x402vip.com/api/catalog/openai-functions.json","openapi":"https://x402vip.com/openapi.json","payments":"https://x402vip.com/api/payments","search":"https://x402vip.com/api/catalog/search","sitemap":"https://x402vip.com/sitemap.xml"},"workflow":["Read /.well-known/server402.json, /.well-known/api-catalog, /apis.json, or /llms.txt first.","Read /llms.txt when you need a concise natural-language overview for model context.","Use /api/catalog/search?q=your-task to find matching services.","Inspect service inputSchema, outputSchema, pricing, quality, and discovery.paymentFlow.","Call the service or MCP tool without a token to receive a 402 payment object, or create payment directly with POST /api/payments.","After payment is paid, retry with X-Payment-Token for HTTP or paymentToken for MCP."],"payment":{"type":"http-402","createPayment":{"method":"POST","url":"https://x402vip.com/api/payments","bodySchema":{"properties":{"providerId":{"type":"string"},"serviceId":{"description":"Use the canonical service id from the catalog. Legacy internal ids remain accepted for backward compatibility.","type":"string"}},"required":["serviceId"],"type":"object"},"responseSchema":{"properties":{"amountCents":{"type":"integer"},"billingMode":{"type":"string"},"clientId":{"type":"string"},"currency":{"type":"string"},"expiresAt":{"format":"date-time","type":"string"},"internalServiceId":{"description":"Legacy internal service id, included only for backward compatibility.","type":"string"},"maxCalls":{"type":"integer"},"paidAt":{"format":"date-time","type":"string"},"payTo":{"type":"string"},"paymentId":{"type":"string"},"provider":{"type":"string"},"providerId":{"type":"string"},"remainingCalls":{"type":"integer"},"serviceId":{"description":"Canonical public service id.","type":"string"},"status":{"type":"string"},"token":{"type":"string"},"usedCalls":{"type":"integer"}},"type":"object"}},"verifyPayment":{"method":"GET","url":"https://x402vip.com/api/payments/{paymentId}","responseSchema":{"properties":{"amountCents":{"type":"integer"},"billingMode":{"type":"string"},"clientId":{"type":"string"},"currency":{"type":"string"},"expiresAt":{"format":"date-time","type":"string"},"internalServiceId":{"description":"Legacy internal service id, included only for backward compatibility.","type":"string"},"maxCalls":{"type":"integer"},"paidAt":{"format":"date-time","type":"string"},"payTo":{"type":"string"},"paymentId":{"type":"string"},"provider":{"type":"string"},"providerId":{"type":"string"},"remainingCalls":{"type":"integer"},"serviceId":{"description":"Canonical public service id.","type":"string"},"status":{"type":"string"},"token":{"type":"string"},"usedCalls":{"type":"integer"}},"type":"object"}},"token":{"header":"X-Payment-Token","mcpArgument":"paymentToken","httpUsage":"Send the paid token in the X-Payment-Token request header when calling /api/tools/*.","mcpUsage":"Pass the paid token as the paymentToken argument when calling the MCP tool."},"requiredResponse":{"status":402,"contentType":"application/json","headers":{"PAYMENT-REQUIRED":"base64/json x402PaymentRequired","PAYMENT-SIGNATURE":"base64/json x402 Base USDC payment payload","X-Payment-Required":"true","X-Payment-Token":"payment.token","X402-Guarantee":"base64url/json Xiao Coin escrow guarantee"},"bodySchema":{"properties":{"accepts":{"items":{"type":"object"},"type":"array"},"error":{"type":"string"},"extensions":{"type":"object"},"payment":{"properties":{"amountCents":{"type":"integer"},"billingMode":{"type":"string"},"clientId":{"type":"string"},"currency":{"type":"string"},"expiresAt":{"format":"date-time","type":"string"},"internalServiceId":{"description":"Legacy internal service id, included only for backward compatibility.","type":"string"},"maxCalls":{"type":"integer"},"paidAt":{"format":"date-time","type":"string"},"payTo":{"type":"string"},"paymentId":{"type":"string"},"provider":{"type":"string"},"providerId":{"type":"string"},"remainingCalls":{"type":"integer"},"serviceId":{"description":"Canonical public service id.","type":"string"},"status":{"type":"string"},"token":{"type":"string"},"usedCalls":{"type":"integer"}},"type":"object"},"paymentFlow":{"type":"object"},"resource":{"type":"object"},"retry":{"type":"object"},"type":{"const":"payment_required","type":"string"},"x402Version":{"type":"integer"}},"required":["type","error","payment","paymentFlow","retry"],"type":"object"},"x402Version":2,"x402Header":"PAYMENT-REQUIRED","paymentAsset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","paymentNetwork":"eip155:8453"},"retry":{"when":"Retry after paying one accepts[] requirement with Base USDC x402, Xiao Coin AI wallet escrow, or after payment.status is paid and the legacy token has remaining calls.","http":["Preferred x402 flow: call the paid /api/tools/* endpoint once and read accepts[] from the HTTP 402 response body or PAYMENT-REQUIRED header.","Pay one accepts[] requirement with an x402-compatible wallet/facilitator on network eip155:8453 using Base USDC.","Retry the exact same request with PAYMENT-SIGNATURE set to the base64 JSON x402 payment payload.","XIAO flow: pay the accepts[] requirement where asset=XIAO with the AI wallet, then retry the exact same request with X402-Guarantee set to the base64url guarantee JSON.","Legacy token flow: POST /api/payments with serviceId, complete/verify payment, then retry with X-Payment-Token set to payment.token."],"mcp":["Call the tool without paymentToken to receive payment_required structuredContent.","Preferred x402 clients should pay the accepts[] requirement and call the underlying HTTP endpoint with PAYMENT-SIGNATURE.","XIAO-capable agents should pay the XIAO accepts[] requirement through the AI wallet and call the underlying HTTP endpoint with X402-Guarantee.","Legacy MCP clients can complete or verify payment.paymentId, then call the same MCP tool again with paymentToken set to payment.token."],"examples":{"http402":["curl -i https://example.com/api/tools/timestamp","Read accepts[0].network=eip155:8453, accepts[0].asset=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, accepts[0].amount, and accepts[0].payTo.","curl -H 'PAYMENT-SIGNATURE: \u003cbase64-json-x402-payment-payload\u003e' https://example.com/api/tools/timestamp"],"legacyToken":["curl -X POST https://example.com/api/payments -H 'Content-Type: application/json' -d '{\"serviceId\":\"timestamp\"}'","curl -H 'X-Payment-Token: \u003cpayment.token\u003e' https://example.com/api/tools/timestamp"],"mcp":["Call tool timestamp with no paymentToken.","After payment is complete, call timestamp again with paymentToken=\u003cpayment.token\u003e."],"xiao":["curl -i https://example.com/api/tools/timestamp","Read the accepts[] entry with asset=XIAO, create an AI wallet guarantee for merchant_id=aivps.lat and merchant_order_id=payment.paymentId.","curl -H 'X402-Guarantee: \u003cbase64url-guarantee-json\u003e' https://example.com/api/tools/timestamp"]},"failures":["payment required","payment token expired","payment token has no remaining calls","api key required","api key is not allowed to call this service"]}},"errorHandling":["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."]}