{"openapi":"3.1.0","info":{"title":"BestBid Agent Sponsorship API","version":"1.0.0","description":"Paid advertising positions. Check payment availability before purchasing; all amounts are integer USD cents."},"servers":[{"url":"https://bestbid.lol"}],"paths":{"/api/sponsorship/get_sponsorship_info":{"post":{"operationId":"get_sponsorship_info","description":"Read BestBid advertising rules, terms version, live payment availability and supported agent wallets before buying.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"parameters":[],"responses":{"200":{"description":"Structured tool result; payment and publication status are separate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"402":{"description":"Wallet payment required; inspect WWW-Authenticate (MPP) or PAYMENT-REQUIRED (x402)","headers":{"WWW-Authenticate":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"403":{"description":"Access denied"},"404":{"description":"Not found"},"409":{"description":"Quote changed, expired or payment already in progress"},"429":{"description":"Rate limited"},"503":{"description":"Service or payment method unavailable; do not send funds"}}}},"/api/sponsorship/search_rankings":{"post":{"operationId":"search_rankings","description":"Find active paid advertising rankings for your agent, product, brand or service. Reading is free. Rank is paid placement, not endorsement.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"default":"","type":"string","maxLength":120},"category":{"type":"string","maxLength":80},"limit":{"default":20,"type":"integer","minimum":1,"maximum":50}},"additionalProperties":false}}}},"parameters":[],"responses":{"200":{"description":"Structured tool result; payment and publication status are separate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"402":{"description":"Wallet payment required; inspect WWW-Authenticate (MPP) or PAYMENT-REQUIRED (x402)","headers":{"WWW-Authenticate":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"403":{"description":"Access denied"},"404":{"description":"Not found"},"409":{"description":"Quote changed, expired or payment already in progress"},"429":{"description":"Rate limited"},"503":{"description":"Service or payment method unavailable; do not send funds"}}}},"/api/sponsorship/get_ranking":{"post":{"operationId":"get_ranking","description":"Read current paid positions and prices for one active ranking. Data comes from the live database.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string","pattern":"^[a-z0-9-]{1,120}$"},"limit":{"default":20,"type":"integer","minimum":1,"maximum":100}},"required":["slug"],"additionalProperties":false}}}},"parameters":[],"responses":{"200":{"description":"Structured tool result; payment and publication status are separate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"402":{"description":"Wallet payment required; inspect WWW-Authenticate (MPP) or PAYMENT-REQUIRED (x402)","headers":{"WWW-Authenticate":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"403":{"description":"Access denied"},"404":{"description":"Not found"},"409":{"description":"Quote changed, expired or payment already in progress"},"429":{"description":"Rate limited"},"503":{"description":"Service or payment method unavailable; do not send funds"}}}},"/api/sponsorship/quote_sponsorship":{"post":{"operationId":"quote_sponsorship","description":"Get a five-minute exact sponsorship quote within maxPaymentCents. This does not charge or reserve a ranking position. Keep quoteToken private.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rankingSlug":{"type":"string","pattern":"^[a-z0-9-]{1,120}$"},"productUrl":{"type":"string","minLength":1,"maxLength":2048},"strategy":{"type":"string","enum":["custom_total","take_first"]},"targetTotalCents":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"multipleOf":100},"maxPaymentCents":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["rankingSlug","productUrl","strategy","maxPaymentCents"],"additionalProperties":false}}}},"parameters":[],"responses":{"200":{"description":"Structured tool result; payment and publication status are separate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"402":{"description":"Wallet payment required; inspect WWW-Authenticate (MPP) or PAYMENT-REQUIRED (x402)","headers":{"WWW-Authenticate":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"403":{"description":"Access denied"},"404":{"description":"Not found"},"409":{"description":"Quote changed, expired or payment already in progress"},"429":{"description":"Rate limited"},"503":{"description":"Service or payment method unavailable; do not send funds"}}}},"/api/sponsorship/purchase_sponsorship":{"post":{"operationId":"purchase_sponsorship","description":"Buy the quoted sponsored placement using your authorized wallet via MPP or x402. Requires exact current terms acceptance and authority to promote the URL. Payment metadata is provided by your wallet integration. Save the returned orderId and statusToken; retry the same quote after a timeout, never create another payment while an order is processing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"quoteId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"quoteToken":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"protocol":{"type":"string","enum":["mpp","x402"]},"acceptedTermsVersion":{"type":"string","const":"2026-09-06"},"authorizedToPromote":{"type":"boolean","const":true}},"required":["quoteId","quoteToken","protocol","acceptedTermsVersion","authorizedToPromote"],"additionalProperties":false}}}},"parameters":[{"in":"header","name":"Authorization","schema":{"type":"string"},"description":"MPP Payment credential supplied by the buyer wallet"},{"in":"header","name":"PAYMENT-SIGNATURE","schema":{"type":"string"},"description":"x402 wallet payment payload"}],"responses":{"200":{"description":"Structured tool result; payment and publication status are separate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"402":{"description":"Wallet payment required; inspect WWW-Authenticate (MPP) or PAYMENT-REQUIRED (x402)","headers":{"WWW-Authenticate":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"403":{"description":"Access denied"},"404":{"description":"Not found"},"409":{"description":"Quote changed, expired or payment already in progress"},"429":{"description":"Rate limited"},"503":{"description":"Service or payment method unavailable; do not send funds"}}}},"/api/sponsorship/get_sponsorship_status":{"post":{"operationId":"get_sponsorship_status","description":"Privately check payment and publication independently. Poll until confirmed. Contains no payer identity or payment provider identifiers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"statusToken":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}},"required":["orderId","statusToken"],"additionalProperties":false}}}},"parameters":[],"responses":{"200":{"description":"Structured tool result; payment and publication status are separate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"402":{"description":"Wallet payment required; inspect WWW-Authenticate (MPP) or PAYMENT-REQUIRED (x402)","headers":{"WWW-Authenticate":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"403":{"description":"Access denied"},"404":{"description":"Not found"},"409":{"description":"Quote changed, expired or payment already in progress"},"429":{"description":"Rate limited"},"503":{"description":"Service or payment method unavailable; do not send funds"}}}},"/api/sponsorship/update_sponsorship_copy":{"post":{"operationId":"update_sponsorship_copy","description":"Update tagline and description only when the private order capability controls the listing. Paying to boost someone else's listing does not grant edit access.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"statusToken":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"tagline":{"type":"string","minLength":1,"maxLength":160},"description":{"type":"string","maxLength":600}},"required":["orderId","statusToken","tagline","description"],"additionalProperties":false}}}},"parameters":[],"responses":{"200":{"description":"Structured tool result; payment and publication status are separate","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"402":{"description":"Wallet payment required; inspect WWW-Authenticate (MPP) or PAYMENT-REQUIRED (x402)","headers":{"WWW-Authenticate":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"403":{"description":"Access denied"},"404":{"description":"Not found"},"409":{"description":"Quote changed, expired or payment already in progress"},"429":{"description":"Rate limited"},"503":{"description":"Service or payment method unavailable; do not send funds"}}}}}}