{"openapi":"3.1.0","info":{"title":"CryptoAd Network Agent API","version":"1","summary":"Buy ads without an account, paying with USDC on Base through x402.","contact":{"name":"CryptoAd Network","email":"sales@cryptoadvertising.net","url":"https://cryptoadvertising.net/agents"},"x-guidance":"Crypto advertising that an agent buys on its own. 1) GET /api/v1/formats for the formats, fields and prices. 2) POST /api/v1/quote with an order for its exact price; nothing is created. 3) POST /api/v1/ads with the same order and a new random UUID in the Idempotency-Key header: the answer is 402 with an x402 v2 payment requirement. 4) Sign the payment and repeat the identical request with the PAYMENT-SIGNATURE header: 201 with the ad and an API key. Store the key; it is shown once. 5) Poll GET /api/v1/ads/{id}. The cheapest order is ten paid-to-click views. More: /llms.txt.","description":"An HTTP API for autonomous agents. Quote an order, pay for it with USDC on Base using the x402 protocol (version 2), and the order is placed in the same exchange. No sign-up, no email, no browser.\n\nJSON in, JSON out. Field names are snake_case. Money is a decimal string, never a number. Every answer carries `request_id` (and the `X-Request-Id` header). An error is `{\"error\": {\"code\", \"message\", \"field\"?, \"reason\"?}, \"request_id\"}`; branch on `code`.\n\nEvery ad is reviewed before it goes live. Placing an order returns it as `in_review`; poll `GET /api/v1/ads/{id}`. There are no webhooks."},"servers":[{"url":"https://cryptoadvertising.net"}],"paths":{"/api/v1":{"get":{"operationId":"getIndex","summary":"Index: name, version, links to every document, and whether payments are available.","security":[],"description":"Start here. Says what this API is, where its documents are, how to authenticate, and whether the payment rail is available on this deployment.","responses":{"200":{"description":"The index.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Index"},"example":{"name":"CryptoAd Network Agent API","version":"1","description":"Buy ads without an account: get a quote, pay with USDC on Base through x402, and the order is placed in the same exchange.","documentation":{"openapi":"https://cryptoadvertising.net/api/v1/openapi.json","formats":"https://cryptoadvertising.net/api/v1/formats","llms_txt":"https://cryptoadvertising.net/llms.txt"},"authentication":{"scheme":"bearer","header":"Authorization: Bearer can_live_…","obtain":"POST /api/v1/keys, or place a first order without a key and pay for it: the answer carries the key."},"payments":{"status":"available","protocol":"x402","x402_version":2,"scheme":"exact","network":"eip155:8453","chain_id":8453,"asset":{"symbol":"USDC","address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6},"pay_to":"(the recipient address in the live 402 answer)","min_topup_usd":"1.00","max_payment_usd":"10000.00"},"endpoints":[{"method":"GET","path":"/api/v1","auth":"none","idempotency_key":false,"summary":"Index: name, version, links to every document, and whether payments are available."},{"method":"GET","path":"/api/v1/openapi.json","auth":"none","idempotency_key":false,"summary":"This API as an OpenAPI 3.1 document, with examples."}],"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApi","summary":"This API as an OpenAPI 3.1 document, with examples.","security":[],"description":"This document.","responses":{"200":{"description":"An OpenAPI 3.1 document.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/formats":{"get":{"operationId":"listFormats","summary":"The catalog: every ad format with its fields, limits, pricing models and prices.","security":[],"description":"Every format with its fields, limits, pricing models, minimum and maximum bids, an example order and that example's price. `available` says whether the format can be ordered on this deployment right now.","responses":{"200":{"description":"The catalog.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Formats"},"example":{"currency":"USD","money":"Every amount is a decimal string, never a number. Budgets and prices have two decimals; a bid may have up to eight.","formats":[{"product":"Banner","available":true,"unavailable_reason":null,"example":{"order":{"product":"Banner","name":"Autumn banner","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","targeting":{"countries":["US","GB"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]}},"price_usd":"50.00"}}],"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/quote":{"post":{"operationId":"quoteOrder","summary":"Validate an order and return its exact price and breakdown. Creates nothing.","security":[],"description":"Validates an order exactly as placing it would, and returns the price that placing it would charge. Creates nothing and costs nothing. `order` is the order as it was understood, after defaults.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"example":{"product":"Banner","name":"Autumn banner","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","targeting":{"countries":["US","GB"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]}}}}},"responses":{"200":{"description":"The order is valid; this is its price.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteAnswer"},"example":{"quote":{"total_usd":"50.00","exact_usd":"50.00000000","daily_budget_usd":"10.00","lines":[{"code":"total_budget","label":"Total budget","amount_usd":"50.00"}]},"order":{"product":"Banner","name":"Autumn banner","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","targeting":{"countries":["GB","US"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]},"product_options":null,"image_id":null},"available":true,"unavailable_reason":null,"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"400":{"description":"`invalid_json`, `invalid_input`, `bad_product`, `bad_name`, `bad_landing_url`, `bad_ad_title`, `bad_ad_description`, `bad_pricing_model`, `bad_bid`, `bid_below_minimum`, `bid_above_maximum`, `bid_above_daily_budget`, `bad_budget`, `budget_below_minimum`, `daily_above_total`, `order_too_large`, `bad_countries`, `bad_devices`, `bad_publisher_blocklist`, `unsupported_targeting`, `missing_product_options`, `bad_clicks`, `bad_duration`, `bad_ad_type`, `bad_daily_limit`, `bad_row`, `bad_weeks`, `bad_brand_name`, `bad_call_to_action`, `bad_required_seconds`, `bad_creative`, `missing_creative`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_json":{"value":{"error":{"code":"invalid_json","message":"The body must be one JSON object."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"invalid_input":{"value":{"error":{"code":"invalid_input","message":"The request is not valid. See `field`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_product":{"value":{"error":{"code":"bad_product","message":"Unknown product. Use a `product` from /api/v1/formats, spelled exactly so."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_name":{"value":{"error":{"code":"bad_name","message":"The name is missing, too long for this product, or not a single line of text."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_landing_url":{"value":{"error":{"code":"bad_landing_url","message":"The landing URL must be an https URL with a host name, in ASCII, within the product's length limit."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_ad_title":{"value":{"error":{"code":"bad_ad_title","message":"The title is missing or outside the length this product allows."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_ad_description":{"value":{"error":{"code":"bad_ad_description","message":"The description is missing or outside the length this product allows, or the product takes none."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_pricing_model":{"value":{"error":{"code":"bad_pricing_model","message":"This product does not offer that pricing model, or it must be named."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_bid":{"value":{"error":{"code":"bad_bid","message":"The bid must be a decimal string such as \"0.05\", or the product takes no bid."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bid_below_minimum":{"value":{"error":{"code":"bid_below_minimum","message":"The bid is below the minimum for this product and pricing model."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bid_above_maximum":{"value":{"error":{"code":"bid_above_maximum","message":"The bid is above the maximum for this product and pricing model."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bid_above_daily_budget":{"value":{"error":{"code":"bid_above_daily_budget","message":"One click or visit at this bid does not fit in the daily budget."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_budget":{"value":{"error":{"code":"bad_budget","message":"The budget must be a decimal string above zero with at most two decimals."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"budget_below_minimum":{"value":{"error":{"code":"budget_below_minimum","message":"The total budget is below the minimum order."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"daily_above_total":{"value":{"error":{"code":"daily_above_total","message":"The daily budget cannot exceed the total budget."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"order_too_large":{"value":{"error":{"code":"order_too_large","message":"The order is above the largest order accepted."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_countries":{"value":{"error":{"code":"bad_countries","message":"Countries must be a list of ISO 3166-1 alpha-2 codes."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_devices":{"value":{"error":{"code":"bad_devices","message":"Devices must be DESKTOP, MOBILE or TABLET, in a combination this product supports."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_publisher_blocklist":{"value":{"error":{"code":"bad_publisher_blocklist","message":"The publisher blocklist must be a list of domain names within the limit."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"unsupported_targeting":{"value":{"error":{"code":"unsupported_targeting","message":"This product cannot enforce that targeting, so it is refused rather than ignored."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"missing_product_options":{"value":{"error":{"code":"missing_product_options","message":"This product needs `product_options`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_clicks":{"value":{"error":{"code":"bad_clicks","message":"The number of clicks is outside the allowed range."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_duration":{"value":{"error":{"code":"bad_duration","message":"The view time is not one of the allowed durations."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_ad_type":{"value":{"error":{"code":"bad_ad_type","message":"The ad type must be FRAMED or FRAMELESS."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_daily_limit":{"value":{"error":{"code":"bad_daily_limit","message":"The daily click limit must be 0 (none) or at least the minimum, and not above the clicks ordered."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_row":{"value":{"error":{"code":"bad_row","message":"The row is not one that can be booked."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_weeks":{"value":{"error":{"code":"bad_weeks","message":"The number of weeks is not one that can be booked."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_brand_name":{"value":{"error":{"code":"bad_brand_name","message":"The brand name is missing or outside the allowed length."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_call_to_action":{"value":{"error":{"code":"bad_call_to_action","message":"The call to action is missing or outside the allowed length."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_required_seconds":{"value":{"error":{"code":"bad_required_seconds","message":"The required view time is outside the allowed range."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_creative":{"value":{"error":{"code":"bad_creative","message":"The image does not exist for this key, or this product takes no image."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"missing_creative":{"value":{"error":{"code":"missing_creative","message":"This product needs an image: upload one with POST /api/v1/images and send its id as image_id."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"413":{"description":"`body_too_large`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"body_too_large":{"value":{"error":{"code":"body_too_large","message":"The request body is too large."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/keys":{"post":{"operationId":"createKey","summary":"Create an anonymous account with a zero balance and return its API key.","security":[],"description":"Creates an anonymous account with a zero balance and returns its API key. The key is shown in this one answer and never again: only a hash of it is stored. Store it before doing anything else. Send no body, or `{}`.\n\nThe Idempotency-Key of this request must be a random UUID (or 32+ random characters): without an API key it is a secret. A repeat with the same Idempotency-Key does not create a second account and is NOT given a key: it answers `409 key_already_issued`. If the key was lost, call again with a new Idempotency-Key; a new empty account costs nothing, and the unused one is removed after a week.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"The account and its key.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyAnswer"},"example":{"api_key":"can_live_REPLACE_WITH_THE_KEY_YOU_WERE_GIVEN","api_key_status":"issued","balance":{"available_usd":"0.00","reserved_usd":"0.00","total_usd":"0.00"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"400":{"description":"`invalid_json`, `invalid_input`, `idempotency_key_required`, `idempotency_key_invalid`, `idempotency_key_weak`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_json":{"value":{"error":{"code":"invalid_json","message":"The body must be one JSON object."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"invalid_input":{"value":{"error":{"code":"invalid_input","message":"The request is not valid. See `field`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_required":{"value":{"error":{"code":"idempotency_key_required","message":"This request needs an Idempotency-Key header."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_invalid":{"value":{"error":{"code":"idempotency_key_invalid","message":"The Idempotency-Key must be 16 to 128 characters from A-Z, a-z, 0-9, and . _ : -. A random UUID is a good one."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_weak":{"value":{"error":{"code":"idempotency_key_weak","message":"Without an API key the Idempotency-Key is a secret: it must be a random UUID (or at least 32 random characters of A-Z, a-z, 0-9, _ and -). Generate 128 random bits for every new request; never reuse it and never log it."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"409":{"description":"`idempotency_key_reused`, `request_in_progress`, `key_already_issued`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"value":{"error":{"code":"idempotency_key_reused","message":"This Idempotency-Key was already used for a different request. Use a new key for a new request."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"request_in_progress":{"value":{"error":{"code":"request_in_progress","message":"A request with this Idempotency-Key is being processed. Repeat it after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"key_already_issued":{"value":{"error":{"code":"key_already_issued","message":"This Idempotency-Key already created an account, and its API key was shown once. It is never shown again. If the key was not stored, call POST /api/v1/keys with a new Idempotency-Key: a new empty account costs nothing."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"413":{"description":"`body_too_large`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"body_too_large":{"value":{"error":{"code":"body_too_large","message":"The request body is too large."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/ads":{"post":{"operationId":"createAd","summary":"Place an order. Paid from the key's balance, or with an x402 payment in the same exchange.","security":[{"apiKey":[]},{}],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.05"},"protocols":[{"x402":{}}]},"description":"Places an order.\n\n**With a key whose balance covers the price:** the order is placed and paid from the balance (`201`).\n\n**Otherwise:** the answer is `402` with an x402 payment requirement for the exact price (`PAYMENT-REQUIRED` header, and `payment_required` in the body). Sign it and repeat the SAME request (same body, same Idempotency-Key) with the `PAYMENT-SIGNATURE` header. The server settles the payment, confirms it on chain, credits it, places the order and answers `201` with the ad and the receipt.\n\n**Without a key**, that `201` also carries `api_key`: the key of the anonymous account that now owns the ad. Store it at once. The Idempotency-Key of such a request is a bearer secret and must be a random UUID (or 32+ random characters).\n\nNothing is created before the payment is confirmed. A repeat with the same Idempotency-Key never pays twice and never places a second ad: it resumes, or returns the stored answer (`Idempotent-Replayed: true`).\n\nA repeat of a request made without a key is given a key again only if it carries the SAME `PAYMENT-SIGNATURE` header that paid, within 24 hours of the first answer, and while no key of the account has been used. Otherwise it returns the stored answer with `api_key: null` and `api_key_recovery`: `repeat_with_payment_header` (send the header that paid) or `support_wallet_proof` (the account can only be recovered through support, with proof of control of the paying wallet).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/PaymentSignature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"example":{"product":"Banner","name":"Autumn banner","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","targeting":{"countries":["US","GB"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]}}}}},"responses":{"201":{"description":"The order is placed and is waiting for review.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"x402 SettlementResponse, base64-encoded JSON: success, transaction hash, network, payer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdCreated"},"example":{"ad":{"id":1042,"name":"Autumn banner","product":"Banner","status":"in_review","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","spent_usd":"0.00","remaining_usd":"50.00","spent_today_usd":"0.00","impressions":0,"clicks":0,"conversions":0,"targeting":{"countries":["GB","US"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]},"product_options":null,"image":null,"rejection_reason":null,"created_at":"2026-11-11T09:00:00.000Z","activated_at":null,"ends_at":null,"completed_at":null,"archived_at":null},"payment":{"id":77,"status":"credited","amount_usd":"50.00","network":"eip155:8453","tx_hash":"0x8f2a6c1d4e7b9a035c2d1e4f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7","payer":"0x857b06519e91e3a54538791bdbb0e22373e36b66","credited_at":"2026-11-11T09:00:04.000Z"},"balance":{"available_usd":"0.00","reserved_usd":"50.00","total_usd":"50.00"},"api_key":"can_live_REPLACE_WITH_THE_KEY_YOU_WERE_GIVEN","api_key_status":"issued","request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"400":{"description":"`invalid_json`, `invalid_input`, `bad_product`, `bad_name`, `bad_landing_url`, `bad_ad_title`, `bad_ad_description`, `bad_pricing_model`, `bad_bid`, `bid_below_minimum`, `bid_above_maximum`, `bid_above_daily_budget`, `bad_budget`, `budget_below_minimum`, `daily_above_total`, `order_too_large`, `bad_countries`, `bad_devices`, `bad_publisher_blocklist`, `unsupported_targeting`, `missing_product_options`, `bad_clicks`, `bad_duration`, `bad_ad_type`, `bad_daily_limit`, `bad_row`, `bad_weeks`, `bad_brand_name`, `bad_call_to_action`, `bad_required_seconds`, `bad_creative`, `missing_creative`, `idempotency_key_required`, `idempotency_key_invalid`, `idempotency_key_weak`, `invalid_payment`, `payment_mismatch`, `payment_above_maximum`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_json":{"value":{"error":{"code":"invalid_json","message":"The body must be one JSON object."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"invalid_input":{"value":{"error":{"code":"invalid_input","message":"The request is not valid. See `field`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_product":{"value":{"error":{"code":"bad_product","message":"Unknown product. Use a `product` from /api/v1/formats, spelled exactly so."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_name":{"value":{"error":{"code":"bad_name","message":"The name is missing, too long for this product, or not a single line of text."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_landing_url":{"value":{"error":{"code":"bad_landing_url","message":"The landing URL must be an https URL with a host name, in ASCII, within the product's length limit."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_ad_title":{"value":{"error":{"code":"bad_ad_title","message":"The title is missing or outside the length this product allows."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_ad_description":{"value":{"error":{"code":"bad_ad_description","message":"The description is missing or outside the length this product allows, or the product takes none."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_pricing_model":{"value":{"error":{"code":"bad_pricing_model","message":"This product does not offer that pricing model, or it must be named."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_bid":{"value":{"error":{"code":"bad_bid","message":"The bid must be a decimal string such as \"0.05\", or the product takes no bid."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bid_below_minimum":{"value":{"error":{"code":"bid_below_minimum","message":"The bid is below the minimum for this product and pricing model."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bid_above_maximum":{"value":{"error":{"code":"bid_above_maximum","message":"The bid is above the maximum for this product and pricing model."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bid_above_daily_budget":{"value":{"error":{"code":"bid_above_daily_budget","message":"One click or visit at this bid does not fit in the daily budget."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_budget":{"value":{"error":{"code":"bad_budget","message":"The budget must be a decimal string above zero with at most two decimals."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"budget_below_minimum":{"value":{"error":{"code":"budget_below_minimum","message":"The total budget is below the minimum order."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"daily_above_total":{"value":{"error":{"code":"daily_above_total","message":"The daily budget cannot exceed the total budget."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"order_too_large":{"value":{"error":{"code":"order_too_large","message":"The order is above the largest order accepted."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_countries":{"value":{"error":{"code":"bad_countries","message":"Countries must be a list of ISO 3166-1 alpha-2 codes."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_devices":{"value":{"error":{"code":"bad_devices","message":"Devices must be DESKTOP, MOBILE or TABLET, in a combination this product supports."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_publisher_blocklist":{"value":{"error":{"code":"bad_publisher_blocklist","message":"The publisher blocklist must be a list of domain names within the limit."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"unsupported_targeting":{"value":{"error":{"code":"unsupported_targeting","message":"This product cannot enforce that targeting, so it is refused rather than ignored."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"missing_product_options":{"value":{"error":{"code":"missing_product_options","message":"This product needs `product_options`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_clicks":{"value":{"error":{"code":"bad_clicks","message":"The number of clicks is outside the allowed range."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_duration":{"value":{"error":{"code":"bad_duration","message":"The view time is not one of the allowed durations."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_ad_type":{"value":{"error":{"code":"bad_ad_type","message":"The ad type must be FRAMED or FRAMELESS."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_daily_limit":{"value":{"error":{"code":"bad_daily_limit","message":"The daily click limit must be 0 (none) or at least the minimum, and not above the clicks ordered."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_row":{"value":{"error":{"code":"bad_row","message":"The row is not one that can be booked."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_weeks":{"value":{"error":{"code":"bad_weeks","message":"The number of weeks is not one that can be booked."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_brand_name":{"value":{"error":{"code":"bad_brand_name","message":"The brand name is missing or outside the allowed length."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_call_to_action":{"value":{"error":{"code":"bad_call_to_action","message":"The call to action is missing or outside the allowed length."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_required_seconds":{"value":{"error":{"code":"bad_required_seconds","message":"The required view time is outside the allowed range."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"bad_creative":{"value":{"error":{"code":"bad_creative","message":"The image does not exist for this key, or this product takes no image."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"missing_creative":{"value":{"error":{"code":"missing_creative","message":"This product needs an image: upload one with POST /api/v1/images and send its id as image_id."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_required":{"value":{"error":{"code":"idempotency_key_required","message":"This request needs an Idempotency-Key header."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_invalid":{"value":{"error":{"code":"idempotency_key_invalid","message":"The Idempotency-Key must be 16 to 128 characters from A-Z, a-z, 0-9, and . _ : -. A random UUID is a good one."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_weak":{"value":{"error":{"code":"idempotency_key_weak","message":"Without an API key the Idempotency-Key is a secret: it must be a random UUID (or at least 32 random characters of A-Z, a-z, 0-9, _ and -). Generate 128 random bits for every new request; never reuse it and never log it."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"invalid_payment":{"value":{"error":{"code":"invalid_payment","message":"The PAYMENT-SIGNATURE header is not an x402 v2 payment this API accepts (scheme exact, EIP-3009). See `reason`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_mismatch":{"value":{"error":{"code":"payment_mismatch","message":"The signed payment does not match the payment requirement of this request. See `reason`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_above_maximum":{"value":{"error":{"code":"payment_above_maximum","message":"The amount is above the largest single payment. Top up the balance in parts, then order with the key."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"402":{"description":"`payment_required`: pay this and repeat the request. Also `payment_verification_failed` and `payment_failed`.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"PAYMENT-REQUIRED":{"description":"x402 PaymentRequired, base64-encoded JSON. The same object is in the body as `payment_required`.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"x402 SettlementResponse, base64-encoded JSON: success, transaction hash, network, payer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredAnswer"},"examples":{"payment_required":{"value":{"error":{"code":"payment_required","message":"Payment required. Sign the x402 payment in PAYMENT-REQUIRED and repeat this request with the PAYMENT-SIGNATURE header."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b","quote":{"total_usd":"50.00","exact_usd":"50.00000000","daily_budget_usd":"10.00","lines":[{"code":"total_budget","label":"Total budget","amount_usd":"50.00"}]},"payment_required":{"x402Version":2,"resource":{"url":"https://cryptoadvertising.net/api/v1/ads","description":"Buy crypto advertising without an account. Place a PTC, banner, native, paid-visit or sponsored-listing ad that is shown to real crypto users, pay the quoted price in USDC, and the ad goes to review. Formats and prices: GET /api/v1/formats.","mimeType":"application/json"},"accepts":[{"scheme":"exact","network":"eip155:8453","amount":"50000000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"(the recipient address in the live 402 answer)","maxTimeoutSeconds":600,"extra":{"name":"USD Coin","version":"2"}}]}}},"payment_verification_failed":{"value":{"error":{"code":"payment_verification_failed","message":"The payment was refused before anything was sent to the chain. See `reason`. Nothing was charged; a new signature may be submitted.","reason":"insufficient_funds"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_failed":{"value":{"error":{"code":"payment_failed","message":"The payment did not go through. See `reason`, and `payment.status` for whether that is final.","reason":"authorization_expired"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b","payment":{"id":77,"status":"failed","amount_usd":"50.00","network":"eip155:8453","tx_hash":null,"payer":"0x857b06519e91e3a54538791bdbb0e22373e36b66","credited_at":null}}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"409":{"description":"`idempotency_key_reused`, `request_in_progress`, `payment_already_used`, `payment_in_progress`, `payment_pending`, `order_not_placed`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"value":{"error":{"code":"idempotency_key_reused","message":"This Idempotency-Key was already used for a different request. Use a new key for a new request."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"request_in_progress":{"value":{"error":{"code":"request_in_progress","message":"A request with this Idempotency-Key is being processed. Repeat it after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_already_used":{"value":{"error":{"code":"payment_already_used","message":"This signed payment has already paid for another request."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_in_progress":{"value":{"error":{"code":"payment_in_progress","message":"Another signed payment for this request is still settling. Repeat the request with that payment, or wait until it has expired."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_pending":{"value":{"error":{"code":"payment_pending","message":"The payment was sent and is not confirmed on chain yet. Repeat the same request after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"order_not_placed":{"value":{"error":{"code":"order_not_placed","message":"The payment was credited to the balance, but the order was not placed. See `reason`. Order again from the balance with a new Idempotency-Key."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"413":{"description":"`body_too_large`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"body_too_large":{"value":{"error":{"code":"body_too_large","message":"The request body is too large."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"502":{"description":"`order_refused`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"order_refused":{"value":{"error":{"code":"order_refused","message":"The system that delivers this ad refused to create it. Nothing stays reserved: the amount is in the balance."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"503":{"description":"`payments_unavailable`, `payment_provider_unavailable`, `product_unavailable`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"payments_unavailable":{"value":{"error":{"code":"payments_unavailable","message":"Payments are not available on this deployment at the moment, so nothing can be paid for."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_provider_unavailable":{"value":{"error":{"code":"payment_provider_unavailable","message":"The payment could not be processed right now. No funds were moved by this attempt; repeat the request."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"product_unavailable":{"value":{"error":{"code":"product_unavailable","message":"This product cannot be ordered at the moment."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}},"get":{"operationId":"listAds","summary":"The key's ads, newest first.","security":[{"apiKey":[]}],"description":"The ads of this key, newest first. Reading also picks up review decisions and finishes ads that have completed.","parameters":[{"name":"limit","in":"query","description":"How many ads to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"before","in":"query","description":"Return ads with an id below this one: pass `next_before` of the previous page.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"A page of ads.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdList"},"example":{"ads":[{"id":1042,"name":"Autumn banner","product":"Banner","status":"active","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","spent_usd":"1.25","remaining_usd":"48.75","spent_today_usd":"1.25","impressions":0,"clicks":25,"conversions":0,"targeting":{"countries":["GB","US"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]},"product_options":null,"image":null,"rejection_reason":null,"created_at":"2026-11-11T09:00:00.000Z","activated_at":"2026-11-11T10:30:00.000Z","ends_at":null,"completed_at":null,"archived_at":null}],"next_before":null,"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"400":{"description":"`invalid_input`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_input":{"value":{"error":{"code":"invalid_input","message":"The request is not valid. See `field`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/ads/{id}":{"get":{"operationId":"getAd","summary":"One ad: status, spend, what remains, and the reason if it was rejected.","security":[{"apiKey":[]}],"description":"One ad. Poll this to follow review: `in_review`, then `active` or `rejected` (with `rejection_reason`; the budget is then back in the balance).","parameters":[{"$ref":"#/components/parameters/AdId"}],"responses":{"200":{"description":"The ad.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdAnswer"},"example":{"ad":{"id":1042,"name":"Autumn banner","product":"Banner","status":"active","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","spent_usd":"1.25","remaining_usd":"48.75","spent_today_usd":"1.25","impressions":0,"clicks":25,"conversions":0,"targeting":{"countries":["GB","US"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]},"product_options":null,"image":null,"rejection_reason":null,"created_at":"2026-11-11T09:00:00.000Z","activated_at":"2026-11-11T10:30:00.000Z","ends_at":null,"completed_at":null,"archived_at":null},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"code":"not_found","message":"No such resource for this key."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/ads/{id}/stats":{"get":{"operationId":"getAdStats","summary":"Delivery of one ad: totals and a daily series.","security":[{"apiKey":[]}],"description":"Billed delivery of one ad. `daily` is empty until the ad has delivered something; otherwise it has one entry per day, zero-filled.","parameters":[{"$ref":"#/components/parameters/AdId"},{"name":"days","in":"query","description":"How many days back the daily series goes.","schema":{"type":"integer","minimum":1,"maximum":90,"default":14}}],"responses":{"200":{"description":"Totals and the daily series.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdStats"},"example":{"ad_id":1042,"status":"active","totals":{"impressions":0,"clicks":25,"conversions":0,"spent_usd":"1.25","remaining_usd":"48.75"},"days":2,"daily":[{"date":"2026-11-10","impressions":0,"clicks":0,"spend_usd":"0.00"},{"date":"2026-11-11","impressions":0,"clicks":25,"spend_usd":"1.25"}],"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"400":{"description":"`invalid_input`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_input":{"value":{"error":{"code":"invalid_input","message":"The request is not valid. See `field`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"code":"not_found","message":"No such resource for this key."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/ads/{id}/pause":{"post":{"operationId":"pauseAd","summary":"Pause an active ad (Banner, Native, Paid Visits).","security":[{"apiKey":[]}],"description":"Pauses an active ad. Repeating it on a paused ad changes nothing and answers 200. PTC and Sponsored Listing cannot be paused.","parameters":[{"$ref":"#/components/parameters/AdId"}],"responses":{"200":{"description":"The ad after the change.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdLifecycleAnswer"},"example":{"ad":{"id":1042,"name":"Autumn banner","product":"Banner","status":"paused","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","spent_usd":"1.25","remaining_usd":"48.75","spent_today_usd":"1.25","impressions":0,"clicks":25,"conversions":0,"targeting":{"countries":["GB","US"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]},"product_options":null,"image":null,"rejection_reason":null,"created_at":"2026-11-11T09:00:00.000Z","activated_at":"2026-11-11T10:30:00.000Z","ends_at":null,"completed_at":null,"archived_at":null},"balance":{"available_usd":"12.50","reserved_usd":"48.75","total_usd":"61.25"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"code":"not_found","message":"No such resource for this key."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"409":{"description":"`invalid_transition`, `not_pausable`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_transition":{"value":{"error":{"code":"invalid_transition","message":"The ad is not in a state that allows this."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"not_pausable":{"value":{"error":{"code":"not_pausable","message":"This product cannot be paused: its ad is bought when the order is placed."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/ads/{id}/resume":{"post":{"operationId":"resumeAd","summary":"Resume a paused ad.","security":[{"apiKey":[]}],"description":"Resumes a paused ad. Repeating it on an active ad changes nothing and answers 200.","parameters":[{"$ref":"#/components/parameters/AdId"}],"responses":{"200":{"description":"The ad after the change.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdLifecycleAnswer"},"example":{"ad":{"id":1042,"name":"Autumn banner","product":"Banner","status":"active","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","spent_usd":"1.25","remaining_usd":"48.75","spent_today_usd":"1.25","impressions":0,"clicks":25,"conversions":0,"targeting":{"countries":["GB","US"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]},"product_options":null,"image":null,"rejection_reason":null,"created_at":"2026-11-11T09:00:00.000Z","activated_at":"2026-11-11T10:30:00.000Z","ends_at":null,"completed_at":null,"archived_at":null},"balance":{"available_usd":"12.50","reserved_usd":"48.75","total_usd":"61.25"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"code":"not_found","message":"No such resource for this key."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"409":{"description":"`invalid_transition`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_transition":{"value":{"error":{"code":"invalid_transition","message":"The ad is not in a state that allows this."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/ads/{id}/archive":{"post":{"operationId":"archiveAd","summary":"End an ad. What it has not spent returns to the balance.","security":[{"apiKey":[]}],"description":"Ends an ad for good. What it has not spent returns to the balance, once. Repeating it on an archived ad changes nothing and answers 200. PTC and Sponsored Listing cannot be archived while in review or live.","parameters":[{"$ref":"#/components/parameters/AdId"}],"responses":{"200":{"description":"The ad after the change.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdLifecycleAnswer"},"example":{"ad":{"id":1042,"name":"Autumn banner","product":"Banner","status":"archived","landing_url":"https://example.com/autumn","ad_title":"Trade with lower fees","ad_description":"Open an account in two minutes.","pricing_model":"CPC","bid_usd":"0.05","daily_budget_usd":"10.00","total_budget_usd":"50.00","spent_usd":"1.25","remaining_usd":"0.00","spent_today_usd":"1.25","impressions":0,"clicks":25,"conversions":0,"targeting":{"countries":["GB","US"],"devices":["MOBILE"],"publisher_blocklist":["unwanted.example"]},"product_options":null,"image":null,"rejection_reason":null,"created_at":"2026-11-11T09:00:00.000Z","activated_at":"2026-11-11T10:30:00.000Z","ends_at":null,"completed_at":null,"archived_at":null},"balance":{"available_usd":"12.50","reserved_usd":"48.75","total_usd":"61.25"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"404":{"description":"`not_found`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_found":{"value":{"error":{"code":"not_found","message":"No such resource for this key."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"409":{"description":"`invalid_transition`, `not_cancellable`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_transition":{"value":{"error":{"code":"invalid_transition","message":"The ad is not in a state that allows this."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"not_cancellable":{"value":{"error":{"code":"not_cancellable","message":"This product cannot be archived while it is in review or live: its ad is bought when the order is placed."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/images":{"post":{"operationId":"uploadImage","summary":"Upload an image for a Paid Visits ad.","security":[{"apiKey":[]}],"description":"Stores an image for a Paid Visits ad and returns its id for `image_id`. Send the file as the raw request body (any `image/*` or `application/octet-stream` content type), or as `multipart/form-data` in a field named `file`. The type is read from the bytes: PNG, JPEG, WebP or GIF.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"The stored image.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageAnswer"},"example":{"image":{"id":12,"name":"banner.png","url":"https://cryptoadvertising.net/media/0f3c9a1e5b7d42a68c1e0f2b3d4c5e6f.png","mime":"image/png","width":600,"height":400,"bytes":18234,"created_at":"2026-11-11T09:00:00.000Z"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"400":{"description":"`invalid_input`, `empty_file`, `unsupported_format`, `invalid_dimensions`, `idempotency_key_required`, `idempotency_key_invalid`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_input":{"value":{"error":{"code":"invalid_input","message":"The request is not valid. See `field`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"empty_file":{"value":{"error":{"code":"empty_file","message":"The upload is empty."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"unsupported_format":{"value":{"error":{"code":"unsupported_format","message":"The image must be PNG, JPEG, WebP or GIF. The type is read from the bytes."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"invalid_dimensions":{"value":{"error":{"code":"invalid_dimensions","message":"The image is smaller or larger than the allowed dimensions."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_required":{"value":{"error":{"code":"idempotency_key_required","message":"This request needs an Idempotency-Key header."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_invalid":{"value":{"error":{"code":"idempotency_key_invalid","message":"The Idempotency-Key must be 16 to 128 characters from A-Z, a-z, 0-9, and . _ : -. A random UUID is a good one."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"409":{"description":"`too_many_images`, `idempotency_key_reused`, `request_in_progress`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"too_many_images":{"value":{"error":{"code":"too_many_images","message":"This key holds the largest number of images allowed."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_reused":{"value":{"error":{"code":"idempotency_key_reused","message":"This Idempotency-Key was already used for a different request. Use a new key for a new request."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"request_in_progress":{"value":{"error":{"code":"request_in_progress","message":"A request with this Idempotency-Key is being processed. Repeat it after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"413":{"description":"`file_too_large`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"file_too_large":{"value":{"error":{"code":"file_too_large","message":"The image is larger than the limit."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"503":{"description":"`uploads_unavailable`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"uploads_unavailable":{"value":{"error":{"code":"uploads_unavailable","message":"Image uploads are not available on this deployment."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/balance":{"get":{"operationId":"getBalance","summary":"The key's balance: available, reserved, total.","security":[{"apiKey":[]}],"description":"`available_usd` is what a new order can use. `reserved_usd` is the unspent part of the budgets of ads in review or live.","responses":{"200":{"description":"The balance.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceAnswer"},"example":{"balance":{"available_usd":"12.50","reserved_usd":"48.75","total_usd":"61.25"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/balance/topup":{"post":{"operationId":"topUpBalance","summary":"Add funds to the key's balance with an x402 payment.","security":[{"apiKey":[]}],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD"},"protocols":[{"x402":{}}]},"description":"Adds funds to the balance. The same x402 exchange as an order, for an amount you choose: the first answer is `402` with the payment requirement; repeat the same request with `PAYMENT-SIGNATURE`. 1 USDC is credited as $1.00.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/PaymentSignature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopUp"},"example":{"amount_usd":"25.00"}}}},"responses":{"200":{"description":"The payment is confirmed and credited.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"x402 SettlementResponse, base64-encoded JSON: success, transaction hash, network, payer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopUpAnswer"},"example":{"payment":{"id":78,"status":"credited","amount_usd":"25.00","network":"eip155:8453","tx_hash":"0x8f2a6c1d4e7b9a035c2d1e4f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7","payer":"0x857b06519e91e3a54538791bdbb0e22373e36b66","credited_at":"2026-11-11T09:00:04.000Z"},"balance":{"available_usd":"25.00","reserved_usd":"0.00","total_usd":"25.00"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"400":{"description":"`invalid_json`, `invalid_input`, `invalid_amount`, `amount_below_minimum`, `idempotency_key_required`, `idempotency_key_invalid`, `invalid_payment`, `payment_mismatch`, `payment_above_maximum`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_json":{"value":{"error":{"code":"invalid_json","message":"The body must be one JSON object."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"invalid_input":{"value":{"error":{"code":"invalid_input","message":"The request is not valid. See `field`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"invalid_amount":{"value":{"error":{"code":"invalid_amount","message":"amount_usd must be a decimal string above zero with at most two decimals, for example \"25.00\"."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"amount_below_minimum":{"value":{"error":{"code":"amount_below_minimum","message":"The amount is below the smallest top-up."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_required":{"value":{"error":{"code":"idempotency_key_required","message":"This request needs an Idempotency-Key header."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"idempotency_key_invalid":{"value":{"error":{"code":"idempotency_key_invalid","message":"The Idempotency-Key must be 16 to 128 characters from A-Z, a-z, 0-9, and . _ : -. A random UUID is a good one."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"invalid_payment":{"value":{"error":{"code":"invalid_payment","message":"The PAYMENT-SIGNATURE header is not an x402 v2 payment this API accepts (scheme exact, EIP-3009). See `reason`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_mismatch":{"value":{"error":{"code":"payment_mismatch","message":"The signed payment does not match the payment requirement of this request. See `reason`."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_above_maximum":{"value":{"error":{"code":"payment_above_maximum","message":"The amount is above the largest single payment. Top up the balance in parts, then order with the key."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"402":{"description":"`payment_required`: pay this and repeat the request. Also `payment_verification_failed` and `payment_failed`.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"PAYMENT-REQUIRED":{"description":"x402 PaymentRequired, base64-encoded JSON. The same object is in the body as `payment_required`.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"x402 SettlementResponse, base64-encoded JSON: success, transaction hash, network, payer.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredAnswer"},"examples":{"payment_required":{"value":{"error":{"code":"payment_required","message":"Payment required. Sign the x402 payment in PAYMENT-REQUIRED and repeat this request with the PAYMENT-SIGNATURE header."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b","payment_required":{"x402Version":2,"resource":{"url":"https://cryptoadvertising.net/api/v1/balance/topup","description":"Add USDC to the advertising balance of a CryptoAd Network API key. The balance pays for PTC, banner, native, paid-visit and sponsored-listing ads shown to real crypto users.","mimeType":"application/json"},"accepts":[{"scheme":"exact","network":"eip155:8453","amount":"25000000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"(the recipient address in the live 402 answer)","maxTimeoutSeconds":600,"extra":{"name":"USD Coin","version":"2"}}]}}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"409":{"description":"`idempotency_key_reused`, `request_in_progress`, `payment_already_used`, `payment_in_progress`, `payment_pending`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"value":{"error":{"code":"idempotency_key_reused","message":"This Idempotency-Key was already used for a different request. Use a new key for a new request."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"request_in_progress":{"value":{"error":{"code":"request_in_progress","message":"A request with this Idempotency-Key is being processed. Repeat it after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_already_used":{"value":{"error":{"code":"payment_already_used","message":"This signed payment has already paid for another request."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_in_progress":{"value":{"error":{"code":"payment_in_progress","message":"Another signed payment for this request is still settling. Repeat the request with that payment, or wait until it has expired."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_pending":{"value":{"error":{"code":"payment_pending","message":"The payment was sent and is not confirmed on chain yet. Repeat the same request after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"413":{"description":"`body_too_large`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"body_too_large":{"value":{"error":{"code":"body_too_large","message":"The request body is too large."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"503":{"description":"`payments_unavailable`, `payment_provider_unavailable`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"payments_unavailable":{"value":{"error":{"code":"payments_unavailable","message":"Payments are not available on this deployment at the moment, so nothing can be paid for."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}},"payment_provider_unavailable":{"value":{"error":{"code":"payment_provider_unavailable","message":"The payment could not be processed right now. No funds were moved by this attempt; repeat the request."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}},"/api/v1/keys/current":{"delete":{"operationId":"revokeKey","summary":"Revoke the key that makes this request.","security":[{"apiKey":[]}],"description":"Revokes the key that makes this request, at once and for good. The account, its ads and its balance stay, but nothing can reach them any more: there is no second credential. `balance` in the answer is what was left behind.","responses":{"200":{"description":"The key no longer works.","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRevoked"},"example":{"revoked":true,"balance":{"available_usd":"0.00","reserved_usd":"0.00","total_usd":"0.00"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}},"401":{"description":"`unauthorized`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthorized":{"value":{"error":{"code":"unauthorized","message":"A valid API key is required: Authorization: Bearer can_live_…"},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"403":{"description":"`account_suspended`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_suspended":{"value":{"error":{"code":"account_suspended","message":"This account is suspended."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"429":{"description":"`rate_limited`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before repeating the request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Repeat after the time in Retry-After."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}},"500":{"description":"`internal_error`","headers":{"X-Request-Id":{"description":"The `request_id` of this answer. Quote it when asking about a request.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"value":{"error":{"code":"internal_error","message":"Something failed on our side. Repeating the same request with the same Idempotency-Key is safe."},"request_id":"req_3f9a1c0e5b7d42a68c1e0f2b"}}}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer can_live_…`. The key is returned once, by POST /api/v1/keys or by a first order paid without a key."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Your own unique id for this request. Send a random UUID (128 random bits), new for every new request. The same key with the same body returns the first answer instead of acting twice; the same key with a different body is 409. WITHOUT an API key it is a bearer secret: it must be a UUID or at least 32 characters of A-Z, a-z, 0-9, _ and -, not a counter or a pattern (`idempotency_key_weak` otherwise); never reuse it and never log it. With an API key, 16 to 128 characters from A-Z, a-z, 0-9 and . _ : - are accepted.","schema":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}},"PaymentSignature":{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 PaymentPayload, base64-encoded JSON: the requirement from the 402 answer, accepted and signed (scheme exact, EIP-3009 transferWithAuthorization).","schema":{"type":"string"}},"AdId":{"name":"id","in":"path","required":true,"description":"The `id` of an ad of this key.","schema":{"type":"integer","minimum":1}}},"schemas":{"ErrorBody":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine code. Branch on this.","enum":["account_suspended","amount_below_minimum","bad_ad_description","bad_ad_title","bad_ad_type","bad_bid","bad_brand_name","bad_budget","bad_call_to_action","bad_clicks","bad_countries","bad_creative","bad_daily_limit","bad_devices","bad_duration","bad_landing_url","bad_name","bad_pricing_model","bad_product","bad_publisher_blocklist","bad_required_seconds","bad_row","bad_weeks","bid_above_daily_budget","bid_above_maximum","bid_below_minimum","body_too_large","budget_below_minimum","daily_above_total","empty_file","file_too_large","idempotency_key_invalid","idempotency_key_required","idempotency_key_reused","idempotency_key_weak","internal_error","invalid_amount","invalid_dimensions","invalid_input","invalid_json","invalid_payment","invalid_transition","key_already_issued","method_not_allowed","missing_creative","missing_product_options","not_cancellable","not_found","not_pausable","order_not_placed","order_refused","order_too_large","payment_above_maximum","payment_already_used","payment_failed","payment_in_progress","payment_mismatch","payment_pending","payment_provider_unavailable","payment_required","payment_verification_failed","payments_unavailable","product_unavailable","rate_limited","request_in_progress","too_many_images","unauthorized","unsupported_format","unsupported_targeting","uploads_unavailable"]},"message":{"type":"string","description":"For a person or a log."},"field":{"type":"string","description":"The offending input, as a path: `bid_usd`, `product_options.clicks`."},"reason":{"type":"string","description":"A detail code where the error has several causes."}}},"Error":{"type":"object","required":["error","request_id"],"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"},"request_id":{"type":"string","description":"Identifies this answer."}}},"Targeting":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"ISO 3166-1 alpha-2 codes. Empty means worldwide.","items":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"devices":{"type":"array","description":"Empty means every device.","items":{"type":"string","enum":["DESKTOP","MOBILE","TABLET"]}},"publisher_blocklist":{"type":"array","description":"Domains the ad must not run on.","items":{"type":"string"}}}},"Order":{"type":"object","description":"An order. Which fields a product takes, and their limits, are in GET /api/v1/formats. An unknown field is refused.","additionalProperties":false,"required":["product","name","landing_url","ad_title"],"properties":{"product":{"type":"string","enum":["PTC","Sponsored Listing","Banner","Native","Paid Visits"]},"name":{"type":"string"},"landing_url":{"type":"string"},"ad_title":{"type":"string"},"ad_description":{"type":"string"},"pricing_model":{"type":"string","enum":["CPC","CPM","CPV","FIXED"],"description":"Required where a product offers more than one."},"bid_usd":{"type":"string","description":"Per click, per 1,000 impressions or per visit. Defaults to the minimum.","pattern":"^\\d+(\\.\\d{1,8})?$"},"daily_budget_usd":{"type":"string","description":"Budget products: the most the ad can spend in a day.","pattern":"^\\d+(\\.\\d{1,8})?$"},"total_budget_usd":{"type":"string","description":"Budget products: the most the ad can spend, and the price of the order.","pattern":"^\\d+(\\.\\d{1,8})?$"},"targeting":{"$ref":"#/components/schemas/Targeting"},"product_options":{"type":"object","description":"Per product; see GET /api/v1/formats."},"image_id":{"type":"integer","description":"Paid Visits only, and required there: an image uploaded under the same key."}}},"Quote":{"type":"object","required":["total_usd","exact_usd","daily_budget_usd","lines"],"properties":{"total_usd":{"type":"string","description":"What is charged: the exact price rounded up to a cent.","pattern":"^\\d+(\\.\\d{1,8})?$"},"exact_usd":{"type":"string","description":"The exact price, with eight decimals.","pattern":"^\\d+(\\.\\d{1,8})?$"},"daily_budget_usd":{"type":"string","description":"The most the ad can spend in a day.","pattern":"^\\d+(\\.\\d{1,8})?$"},"lines":{"type":"array","items":{"type":"object","required":["code","label","amount_usd"],"properties":{"code":{"type":"string"},"label":{"type":"string"},"quantity":{"type":"integer"},"unit_usd":{"type":"string","description":"Price of one unit.","pattern":"^\\d+(\\.\\d{1,8})?$"},"amount_usd":{"type":"string","description":"Amount of this line.","pattern":"^\\d+(\\.\\d{1,8})?$"}}}}}},"QuoteAnswer":{"type":"object","required":["quote","order","available","unavailable_reason","request_id"],"properties":{"quote":{"$ref":"#/components/schemas/Quote"},"order":{"type":"object","description":"The order as understood, after defaults: what would be stored."},"available":{"type":"boolean","description":"Whether this product can be ordered right now."},"unavailable_reason":{"anyOf":[{"type":"string","enum":["disabled","not_configured"]},{"type":"null"}]},"request_id":{"type":"string","description":"Identifies this answer."}}},"Balance":{"type":"object","required":["available_usd","reserved_usd","total_usd"],"properties":{"available_usd":{"type":"string","description":"What a new order can use.","pattern":"^\\d+(\\.\\d{1,8})?$"},"reserved_usd":{"type":"string","description":"Unspent budget of ads in review or live.","pattern":"^\\d+(\\.\\d{1,8})?$"},"total_usd":{"type":"string","description":"available + reserved.","pattern":"^\\d+(\\.\\d{1,8})?$"}}},"Payment":{"type":"object","description":"The receipt of an x402 payment.","required":["id","status","amount_usd","network","tx_hash","payer","credited_at"],"properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["settling","credited","failed"]},"amount_usd":{"type":"string","description":"The amount credited: 1 USDC = $1.00.","pattern":"^\\d+(\\.\\d{1,8})?$"},"network":{"type":"string","description":"CAIP-2 network id, eip155:8453 for Base."},"tx_hash":{"anyOf":[{"type":"string","description":"The transaction on that network."},{"type":"null"}]},"payer":{"anyOf":[{"type":"string","description":"The wallet that paid, lowercase."},{"type":"null"}]},"credited_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"Ad":{"type":"object","required":["id","name","product","status","landing_url","pricing_model","daily_budget_usd","total_budget_usd","spent_usd","remaining_usd","targeting","created_at"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"product":{"type":"string","enum":["PTC","Sponsored Listing","Banner","Native","Paid Visits"]},"status":{"type":"string","enum":["in_review","active","paused","rejected","completed","archived"],"description":"in_review: paid for, waiting for review. active / paused: approved. rejected: refused, budget returned. completed: delivery finished. archived: ended by you."},"landing_url":{"type":"string"},"ad_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"ad_description":{"anyOf":[{"type":"string"},{"type":"null"}]},"pricing_model":{"type":"string","enum":["CPC","CPM","CPV","FIXED"]},"bid_usd":{"anyOf":[{"type":"string","description":"The bid. Null for a fixed price without one.","pattern":"^\\d+(\\.\\d{1,8})?$"},{"type":"null"}]},"daily_budget_usd":{"type":"string","description":"The most the ad can spend in a day.","pattern":"^\\d+(\\.\\d{1,8})?$"},"total_budget_usd":{"type":"string","description":"What was charged and reserved for the ad.","pattern":"^\\d+(\\.\\d{1,8})?$"},"spent_usd":{"type":"string","description":"Billed for delivery. Never above the total.","pattern":"^\\d+(\\.\\d{1,8})?$"},"remaining_usd":{"type":"string","description":"Still reserved. 0.00 once the ad has ended.","pattern":"^\\d+(\\.\\d{1,8})?$"},"spent_today_usd":{"type":"string","description":"Billed today (UTC).","pattern":"^\\d+(\\.\\d{1,8})?$"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversions":{"type":"integer","description":"Completed visits for Paid Visits."},"targeting":{"$ref":"#/components/schemas/Targeting"},"product_options":{"anyOf":[{"type":"object"},{"type":"null"}]},"image":{"anyOf":[{"type":"object","required":["id","url"],"properties":{"id":{"type":"integer"},"url":{"type":"string"}}},{"type":"null"}]},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"activated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"ends_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"archived_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"AdCreated":{"type":"object","required":["ad","payment","balance","request_id"],"properties":{"ad":{"$ref":"#/components/schemas/Ad"},"payment":{"anyOf":[{"$ref":"#/components/schemas/Payment"},{"type":"null"}]},"balance":{"$ref":"#/components/schemas/Balance"},"api_key":{"anyOf":[{"type":"string","description":"Only for an order placed without a key: the key of the account that owns the ad. Shown once."},{"type":"null"}]},"api_key_status":{"type":"string","enum":["issued","reissued","withheld"],"description":"issued: the account's first key. reissued: a repeat that carried the payment header that paid, within 24 hours, before any key of the account was used; the keys given before stay valid until one is used, which then becomes the only one. withheld: no key is shown; see `api_key_recovery`."},"api_key_recovery":{"type":"string","enum":["repeat_with_payment_header","support_wallet_proof"],"description":"Only with `withheld`. repeat_with_payment_header: repeat the request with the PAYMENT-SIGNATURE header that paid for it. support_wallet_proof: no repeat is given a key any more (a key was used, or 24 hours have passed); the account can be recovered only through support, with proof of control of the wallet that paid."},"request_id":{"type":"string","description":"Identifies this answer."}}},"AdAnswer":{"type":"object","required":["ad","request_id"],"properties":{"ad":{"$ref":"#/components/schemas/Ad"},"request_id":{"type":"string","description":"Identifies this answer."}}},"AdLifecycleAnswer":{"type":"object","required":["ad","balance","request_id"],"properties":{"ad":{"$ref":"#/components/schemas/Ad"},"balance":{"$ref":"#/components/schemas/Balance"},"request_id":{"type":"string","description":"Identifies this answer."}}},"AdList":{"type":"object","required":["ads","next_before","request_id"],"properties":{"ads":{"type":"array","items":{"$ref":"#/components/schemas/Ad"}},"next_before":{"anyOf":[{"type":"integer","description":"Pass as `before` for the next page. Null on the last page."},{"type":"null"}]},"request_id":{"type":"string","description":"Identifies this answer."}}},"AdStats":{"type":"object","required":["ad_id","status","totals","days","daily","request_id"],"properties":{"ad_id":{"type":"integer"},"status":{"type":"string","enum":["in_review","active","paused","rejected","completed","archived"]},"totals":{"type":"object","required":["impressions","clicks","conversions","spent_usd","remaining_usd"],"properties":{"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversions":{"type":"integer"},"spent_usd":{"type":"string","description":"Billed in total.","pattern":"^\\d+(\\.\\d{1,8})?$"},"remaining_usd":{"type":"string","description":"Still reserved.","pattern":"^\\d+(\\.\\d{1,8})?$"}}},"days":{"type":"integer"},"daily":{"type":"array","items":{"type":"object","required":["date","impressions","clicks","spend_usd"],"properties":{"date":{"type":"string","format":"date","description":"UTC day."},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"spend_usd":{"type":"string","description":"Billed that day, cut to whole cents.","pattern":"^\\d+(\\.\\d{1,8})?$"}}}},"request_id":{"type":"string","description":"Identifies this answer."}}},"PaymentRequired":{"type":"object","description":"x402 v2 PaymentRequired. Field names are the x402 specification's (camelCase).","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"resource":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"serviceName":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"iconUrl":{"type":"string"}}},"extensions":{"type":"object","description":"x402 extensions. `bazaar` declares how to call this resource (one example call and its JSON Schema), for catalogs of x402 services. A client may ignore it."},"accepts":{"type":"array","items":{"type":"object","required":["scheme","network","amount","asset","payTo","maxTimeoutSeconds","extra"],"properties":{"scheme":{"type":"string","const":"exact"},"network":{"type":"string"},"amount":{"type":"string","description":"Atomic token units."},"asset":{"type":"string","description":"The token contract."},"payTo":{"type":"string","description":"The recipient."},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object","description":"EIP-712 domain of the token.","properties":{"name":{"type":"string"},"version":{"type":"string"}}}}}}}},"PaymentRequiredAnswer":{"type":"object","required":["error","request_id"],"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"},"quote":{"$ref":"#/components/schemas/Quote"},"payment_required":{"$ref":"#/components/schemas/PaymentRequired"},"payment":{"$ref":"#/components/schemas/Payment"},"request_id":{"type":"string","description":"Identifies this answer."}}},"TopUp":{"type":"object","additionalProperties":false,"required":["amount_usd"],"properties":{"amount_usd":{"type":"string","description":"A decimal string with at most two decimals, within the limits in GET /api/v1.","pattern":"^(0|[1-9]\\d*)(\\.\\d{1,2})?$"}}},"TopUpAnswer":{"type":"object","required":["payment","balance","request_id"],"properties":{"payment":{"$ref":"#/components/schemas/Payment"},"balance":{"$ref":"#/components/schemas/Balance"},"request_id":{"type":"string","description":"Identifies this answer."}}},"BalanceAnswer":{"type":"object","required":["balance","request_id"],"properties":{"balance":{"$ref":"#/components/schemas/Balance"},"request_id":{"type":"string","description":"Identifies this answer."}}},"KeyAnswer":{"type":"object","required":["api_key","api_key_status","balance","request_id"],"properties":{"api_key":{"type":"string","description":"The key. Shown in this answer and never again; store it."},"api_key_status":{"type":"string","enum":["issued"]},"balance":{"$ref":"#/components/schemas/Balance"},"request_id":{"type":"string","description":"Identifies this answer."}}},"KeyRevoked":{"type":"object","required":["revoked","balance","request_id"],"properties":{"revoked":{"type":"boolean","const":true},"balance":{"$ref":"#/components/schemas/Balance"},"request_id":{"type":"string","description":"Identifies this answer."}}},"Image":{"type":"object","required":["id","name","url","mime","width","height","bytes","created_at"],"properties":{"id":{"type":"integer","description":"Use as `image_id` in a Paid Visits order."},"name":{"type":"string"},"url":{"type":"string"},"mime":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"bytes":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"ImageAnswer":{"type":"object","required":["image","request_id"],"properties":{"image":{"$ref":"#/components/schemas/Image"},"request_id":{"type":"string","description":"Identifies this answer."}}},"Index":{"type":"object","required":["name","version","documentation","payments","endpoints","request_id"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"documentation":{"type":"object","required":["openapi","formats","llms_txt"],"properties":{"openapi":{"type":"string"},"formats":{"type":"string"},"llms_txt":{"type":"string"}}},"authentication":{"type":"object"},"payments":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["available","unavailable"],"description":"unavailable: nothing can be paid for on this deployment right now; paid requests answer 503 payments_unavailable."}}},"endpoints":{"type":"array","items":{"type":"object"}},"request_id":{"type":"string","description":"Identifies this answer."}}},"Formats":{"type":"object","required":["currency","formats","request_id"],"properties":{"currency":{"type":"string"},"formats":{"type":"array","items":{"type":"object"}},"request_id":{"type":"string","description":"Identifies this answer."}}}}}}