{"openapi":"3.1.0","info":{"title":"AestheticData x402 API - Agent-only, pay-per-call","description":"\n\n**x402-only API for agents.** This service exposes AestheticData resources (brands, merchants) behind HTTP 402 Payment Required. It is built for **LLM agents and automated clients**, not browser users.\n\n---\n\n### How it works (for agents)\n\n1. **Call a paid endpoint** (e.g. `GET /x402/brands`) without payment → you get **402 Payment Required** and a JSON body with:\n   - `price_usdc`, `chain`, `recipient` (pay this amount in USDC on Base to this address).\n\n2. **Pay** the required USDC on **Base** to the given `recipient`. Use any wallet or agent that can send USDC (e.g. Coinbase Wallet, Awal CLI).\n\n3. **Retry the same request** and send proof of payment:\n   - Header: `X-402-Payment: <txHash>`  \n   - The server verifies the on-chain USDC transfer and, if valid, returns the resource (e.g. brand/merchant data).\n\nAll paid endpoints are under the **X402** tag. No traditional API keys or OAuth are required for x402 access; payment proof is the credential.\n\n---\n\n### Use case\n\n- **Filler product data**: brands and merchants (AestheticData backend), optimized for agent consumption.\n- **Consumers**: AI agents and scripts that pay per call in USDC on Base.\n\n---\n\n### Contact\n\n| Developer   | Email | Other |\n|-------------|-------|-------|\n| Zeliang YAO | [zeliang.yao_filler@2925.com](mailto:zeliang.yao_filler@2925.com) | [Website](https://www.hephaestus.fr/) |\n","version":"1.0.0"},"paths":{"/x402/discovery/resources":{"get":{"tags":["X402"],"summary":"X402 Discovery Resources","description":"Bazaar-compatible discovery listing for current x402 resources.\n\nAdapter layer: keeps existing custom x402 payment flow, while exposing metadata\nin a structure compatible with facilitator discovery clients.","operationId":"x402_discovery_resources_x402_discovery_resources_get","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","default":"http","title":"Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/x402/brands":{"get":{"tags":["X402"],"summary":"Get Brands X402","operationId":"get_brands_x402_x402_brands_get","parameters":[{"name":"include_review_pool","in":"query","required":false,"schema":{"type":"boolean","description":"Include non-core review-pool brands (not recommended for production agent usage).","default":false,"title":"Include Review Pool"},"description":"Include non-core review-pool brands (not recommended for production agent usage)."},{"name":"X-402-Payment","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Paid transaction hash on Base USDC used as x402 proof.","title":"X-402-Payment"},"description":"Paid transaction hash on Base USDC used as x402 proof."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandResponseModel_List_Dict_Any__Any___"}}}},"402":{"description":"Payment Required (x402)","content":{"application/json":{"example":{"price_usdc":"0.001","chain":"base","recipient":"0x407ebFbE56172FAC4795541eB5AEF6F463CfC868","reason":"payment_not_found_or_insufficient"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/x402/regulatory/eu/devices":{"get":{"tags":["X402"],"summary":"Get Regulatory Eu Devices X402","operationId":"get_regulatory_eu_devices_x402_x402_regulatory_eu_devices_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page index for pre-built EU dataset pages.","default":1,"title":"Page"},"description":"Page index for pre-built EU dataset pages."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"description":"Requested page size (current prebuilt pages use 5000).","default":5000,"title":"Page Size"},"description":"Requested page size (current prebuilt pages use 5000)."},{"name":"X-402-Payment","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Paid transaction hash on Base USDC used as x402 proof.","title":"X-402-Payment"},"description":"Paid transaction hash on Base USDC used as x402 proof."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment Required (x402)","content":{"application/json":{"example":{"price_usdc":"0.001","chain":"base","recipient":"0x407ebFbE56172FAC4795541eB5AEF6F463CfC868","reason":"payment_not_found_or_insufficient"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/x402/merchants":{"get":{"tags":["X402"],"summary":"Get Merchants X402","description":"Get merchant data via x402 payment. Uses the same price as /x402/brands.","operationId":"get_merchants_x402_x402_merchants_get","parameters":[{"name":"include_review_pool","in":"query","required":false,"schema":{"type":"boolean","description":"Include non-core review-pool merchants (not recommended for production agent usage).","default":false,"title":"Include Review Pool"},"description":"Include non-core review-pool merchants (not recommended for production agent usage)."},{"name":"X-402-Payment","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Paid transaction hash on Base USDC used as x402 proof.","title":"X-402-Payment"},"description":"Paid transaction hash on Base USDC used as x402 proof."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantResponseModel_List_Dict_Any__Any___"}}}},"402":{"description":"Payment Required (x402)","content":{"application/json":{"example":{"price_usdc":"0.001","chain":"base","recipient":"0x407ebFbE56172FAC4795541eB5AEF6F463CfC868","reason":"payment_not_found_or_insufficient"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/healthz":{"get":{"tags":["X402"],"summary":"Healthz","description":"Basic health endpoint for local and tunnel checks.","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Healthz Healthz Get"}}}}}}},"/.well-known/agent.json":{"get":{"tags":["X402"],"summary":"Agent Manifest","operationId":"agent_manifest__well_known_agent_json_get","responses":{"200":{"description":"Agent service manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentManifestModel"},"example":{"name":"AestheticData API","version":"1.0.0","base_url":"https://api.aestheticdata.io","docs_url":"https://api.aestheticdata.io/docs","endpoints":[{"method":"GET","path":"/x402/brands","access":"x402-paid","payment_header":"X-402-Payment","payment_type":"base-usdc-txhash","chain":"base","price_usdc":"0.001","notes":"Default returns curated agent core dataset; add include_review_pool=true to include review pool."},{"method":"GET","path":"/x402/merchants","access":"x402-paid","payment_header":"X-402-Payment","payment_type":"base-usdc-txhash","chain":"base","price_usdc":"0.001","notes":"Default returns curated merchant core dataset; add include_review_pool=true to include review pool."},{"method":"GET","path":"/healthz","access":"free"}],"pricing":{"currency":"USDC","chain":"base","price_usdc":"0.001","recipient":"0x407ebFbE56172FAC4795541eB5AEF6F463CfC868"},"examples":[{"title":"x402 curl flow (brands)","steps":["curl -i https://api.aestheticdata.io/x402/brands","npx awal@latest send 0.001 <recipient> --chain base --json","curl -i -H \"X-402-Payment: <txHash>\" https://api.aestheticdata.io/x402/brands"]}]}}}}}}}},"components":{"schemas":{"AgentEndpointModel":{"properties":{"method":{"type":"string","title":"Method"},"path":{"type":"string","title":"Path"},"access":{"type":"string","title":"Access"},"payment_header":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Header"},"payment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Type"},"chain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chain"},"price_usdc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Usdc"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["method","path","access"],"title":"AgentEndpointModel"},"AgentExampleModel":{"properties":{"title":{"type":"string","title":"Title"},"steps":{"items":{"type":"string"},"type":"array","title":"Steps"}},"type":"object","required":["title","steps"],"title":"AgentExampleModel"},"AgentManifestModel":{"properties":{"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"},"base_url":{"type":"string","title":"Base Url"},"docs_url":{"type":"string","title":"Docs Url"},"endpoints":{"items":{"$ref":"#/components/schemas/AgentEndpointModel"},"type":"array","title":"Endpoints"},"pricing":{"$ref":"#/components/schemas/AgentPricingModel"},"examples":{"items":{"$ref":"#/components/schemas/AgentExampleModel"},"type":"array","title":"Examples"}},"type":"object","required":["name","version","base_url","docs_url","endpoints","pricing","examples"],"title":"AgentManifestModel"},"AgentPricingModel":{"properties":{"currency":{"type":"string","title":"Currency"},"chain":{"type":"string","title":"Chain"},"price_usdc":{"type":"string","title":"Price Usdc"},"recipient":{"type":"string","title":"Recipient"}},"type":"object","required":["currency","chain","price_usdc","recipient"],"title":"AgentPricingModel"},"BrandResponseModel_List_Dict_Any__Any___":{"properties":{"status":{"type":"string","title":"Status","default":"success"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"data":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Data"},"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationModel"},{"type":"null"}]}},"type":"object","title":"BrandResponseModel[List[Dict[Any, Any]]]"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MerchantResponseModel_List_Dict_Any__Any___":{"properties":{"status":{"type":"string","title":"Status","default":"success"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"data":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Data"},"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationModel"},{"type":"null"}]}},"type":"object","title":"MerchantResponseModel[List[Dict[Any, Any]]]"},"PaginationModel":{"properties":{"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"pages":{"type":"integer","title":"Pages"}},"type":"object","required":["total","page","page_size","pages"],"title":"PaginationModel"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"X402","description":"Pay-per-call endpoints for agents. Pay in USDC on Base; send proof in request headers."}]}