{"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, XIAO metadata, OpenAPI, and MCP. When payment is required, open xiaopay.top to obtain XIAO, create the guarantee, and retry with X402-Guarantee.","endpoints":{"agentDemand":"https://x402vip.com/api/agent-demand","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","catalogJson":"https://x402vip.com/api/catalog.json","catalogSummary":"https://x402vip.com/api/catalog.summary.json","demandCapture":"https://x402vip.com/api/demand-capture","discovery":"https://x402vip.com/.well-known/server402.json","genericInvoke":"https://x402vip.com/api/invoke","llms":"https://x402vip.com/llms.txt","mapsTraffic":"https://x402vip.com/api/v1/maps/traffic","mapsTrafficHelp":"https://x402vip.com/api/v1/maps/traffic/help","mapsTrafficManifest":"https://x402vip.com/.well-known/maps-traffic.json","mcp":"https://x402vip.com/mcp","openaiFunctions":"https://x402vip.com/api/catalog/openai-functions.json","openapi":"https://x402vip.com/openapi.json","openapiServices":"https://x402vip.com/openapi.services.json","payments":"https://x402vip.com/api/payments","search":"https://x402vip.com/api/catalog/search","searchAlias":"https://x402vip.com/api/search","sitemap":"https://x402vip.com/sitemap.xml"},"workflow":["Read /.well-known/server402.json, /.well-known/api-catalog, /apis.json, or /llms.txt first.","For compact machine-readable service discovery, read /api/catalog.summary.json; for full details read /api/catalog.json and /openapi.services.json.","Read /api/demand-capture when you need planned APIs that are candidates for launch; these are not callable yet, but early-access requests and attempted candidate paths help prioritize what gets built.","When a service returns HTTP 402, open xiaopay.top to obtain XIAO, create an X402-Guarantee for merchant_id=aivps.lat and merchant_order_id=payment.paymentId, then retry the same request with the guarantee header.","For one-off music playback/open-song intent, search `play popular song music playback`, inspect `popular-music-playback`, call it once to receive a XIAO 0.001 HTTP 402 payment requirement, then retry after payment.","For route, directions, traffic-aware ETA, drive time, distance, 路线规划, 导航路线, 实时路况, 堵车, 开车多久, or 从A到B怎么走 intent, inspect `google-maps-traffic`, call POST /api/v1/maps/traffic once to receive HTTP 402, then retry the same body after payment. This is only for origin + destination routes; nearby/POI/business/place details require a future Places/POI service.","For text-to-video or Chinese 文生视频 demand, search `text to video`, inspect `text-to-video`, call POST /api/tools/text-to-video to submit the async video task, then poll `text-to-video-result` with task_id for task_status and video_url.","For browser automation demand, search the exact subtask first: `web extraction`, `url metadata`, `web screenshot`, `ocr screenshot text extraction`, `pdf table extraction`, `html to pdf webpage`, or `structured data extraction` before requesting full Playwright/Puppeteer automation.","For price intelligence demand, search phrases like total cost, unit price, price comparison, price history, price forecast, hidden fees, quote benchmark, bulk price, enterprise price, cost optimization, buy now or wait, and cheaper alternative.","For popular product demand, search product names plus comparison, lowest price, or deal. Planned product entries expose product.referencePrice and product.buyUrl as seed metadata for discovery.","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; /api/search?q=your-task is a short alias for agents.","Read the search response demandCapture block. It tells you whether the query was recorded, which planned services matched, and the exact requestAccessBody to POST when the published services are missing or incomplete.","Search responses include both services and agents. agents[] uses common field names: id, name, description, endpoint, auth_type, billing_method, pricing, input_schema, output_schema, tags, and category.","Inspect service inputSchema/outputSchema or fetch /schemas/services/{agent-id}/invoke.input.schema.json and /schemas/services/{agent-id}/invoke.output.schema.json.","Call POST /api/services/{agent-id}/invoke, POST /api/tools/{agent-id}, POST /api/invoke, or the MCP tool without payment to receive a 402 payment object; then pay or create payment directly with POST /api/payments.","After payment is paid, retry with X-Payment-Token for HTTP or paymentToken for MCP.","If a planned API matches your task, POST /api/planned-services/request-access with serviceId and useCase so Server402 can prioritize launch. If no planned API matches, submit GET or POST /api/agent-demand with the exact missing task; guessed /api/* paths are also recorded as unmet demand signals."],"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"},"amountMicros":{"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"},"amountMicros":{"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 paymentRequired","X-Payment-Required":"true","X-Payment-Token":"payment.token","X402-Guarantee":"base64url/json XIAO escrow guarantee"},"bodySchema":{"properties":{"accepts":{"items":{"type":"object"},"type":"array"},"error":{"type":"string"},"extensions":{"type":"object"},"payment":{"properties":{"amountCents":{"type":"integer"},"amountMicros":{"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":"XIAO","paymentNetwork":"xiao:internal"},"retry":{"when":"Retry after opening xiaopay.top, obtaining XIAO, and creating one XIAO accepts[] guarantee or after payment.status is paid and the token has remaining calls.","http":["Call the paid /api/tools/* endpoint once and read accepts[] from the HTTP 402 response body or PAYMENT-REQUIRED header.","Open https://xiaopay.top to obtain XIAO, then create an AI wallet guarantee for merchant_id=aivps.lat and merchant_order_id=payment.paymentId.","Retry the exact same request with X402-Guarantee set to the base64url guarantee JSON.","Use POST /api/payments with serviceId when you need a reusable payment token, then retry with X-Payment-Token set to payment.token."],"mcp":["Call the tool without paymentToken to receive payment_required structuredContent.","XIAO-capable agents should open xiaopay.top, obtain XIAO, create the AI wallet guarantee, and call the underlying HTTP endpoint with X402-Guarantee.","Clients that use paymentToken can complete or verify payment.paymentId, then call the same MCP tool again with paymentToken set to payment.token."],"examples":{"mcp":["Call tool timestamp with no paymentToken.","After payment is complete, call timestamp again with paymentToken=\u003cpayment.token\u003e."],"paymentToken":["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"],"xiao":["curl -i https://example.com/api/tools/timestamp","Open https://xiaopay.top, obtain XIAO, and 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.","Search responses include demandCapture guidance for AI/Agent demand recording. `matchedPlannedServices` exposes early-access candidates; `requestAccessBody` is intentionally ready to POST back when the agent cannot find a suitable callable service.","Operator analytics for searched queries, found services, unmet gaps, explicit /api/agent-demand submissions, and guessed Agent paths are available at /api/admin/agent-search-insights.","`popular-music-playback` is a published micro-payment service for agents that ask to play, open, find, search, or queue one song. It returns licensed platform links and royalty-free previewAudio after payment.","`google-maps-traffic` is the published paid Google Maps Routes API service for origin + destination route planning, driving directions, traffic-aware ETA, travel time, static time, traffic delay, distance, legs, steps, and polyline. It does not handle standalone nearby, POI, place details, business hours, reviews, map tiles, or geocoding-only lookup.","`text-to-video` is the published high-demand AI video generation service for prompts, scripts, storyboards, ad concepts, and 文生视频 / 文本生成视频 requests. It returns task_id; `text-to-video-result` returns task_status and video_url.","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.","Planned API pages are explicitly marked planned / early-access and are not callable until launched.","Price planned APIs use /api/prices/*, /api/price/*, /services/{price-intent}, and /services/{price-intent}/llms.txt so agents can express what prices they want to estimate, compare, monitor, forecast, benchmark, or execute.","Popular product planned APIs use three demand tags per product: comparison, lowest-price, and deal; each product entry includes referencePrice, priceCurrency, and buyUrl seed metadata."]}