{"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":{"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","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.","For one-off music playback/open-song intent, search `play popular song music playback`, inspect `popular-music-playback`, call it once to receive a USD 0.001 HTTP 402/x402 payment requirement, then retry after payment.","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 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"},"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":"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.","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.","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."]}