{"openapi":"3.0.0","paths":{"/agent/cart/{id}":{"get":{"operationId":"AgentController_getCart","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The cart as stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartModel"}}}},"404":{"description":"No such cart, product or order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"429":{"description":"Rate limit reached (RATE_LIMIT_EXCEEDED); retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}}},"summary":"Read a cart","tags":["Agent"]}},"/agent/cart/update":{"put":{"operationId":"AgentController_updateCartItem","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCartItemDto"}}}},"responses":{"200":{"description":"The updated cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartModel"}}}},"400":{"description":"Invalid input, or a rule of the shop refused it; the errorCode says which","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"404":{"description":"No such cart, product or order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"410":{"description":"A product or amount is out of stock (CART_PRODUCT_OUT_OF_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"429":{"description":"Rate limit reached (RATE_LIMIT_EXCEEDED); retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}}},"summary":"Update quantity/value of a cart item","tags":["Agent"]}},"/agent/cart/remove":{"delete":{"operationId":"AgentController_removeFromCart","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveFromCartDto"}}}},"responses":{"200":{"description":"The updated cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartModel"}}}},"400":{"description":"Invalid input, or a rule of the shop refused it; the errorCode says which","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"404":{"description":"No such cart, product or order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"429":{"description":"Rate limit reached (RATE_LIMIT_EXCEEDED); retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}}},"summary":"Remove an item from a cart","tags":["Agent"]}},"/agent/order/{id}":{"get":{"operationId":"AgentController_getOrderStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentOrderStatusDto"}}}},"404":{"description":"No such cart, product or order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"429":{"description":"Rate limit reached (RATE_LIMIT_EXCEEDED); retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}}},"summary":"Order status (agent orders only) - never includes redeem codes; gift cards are delivered by email","tags":["Agent"]}},"/agent/products":{"get":{"description":"In-stock products only. Texts (title, description, terms, redeem_instructions, faq) come in the requested locale where a translation exists, in English otherwise. discount is the customer discount in percent, per product (its best amount) and per amount; 0 means sold at or above face value.","operationId":"AgentController_getProducts","parameters":[{"name":"limit","required":false,"in":"query","description":"Products per page; 10 when left out","schema":{"minimum":1,"maximum":100,"type":"number"}},{"name":"offset","required":false,"in":"query","schema":{"minimum":0,"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"category","required":false,"in":"query","schema":{"type":"string"}},{"name":"country","required":false,"in":"query","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"Language of the texts; English when left out","schema":{"enum":["en","es","fr","de","ro","pt","zh","hi","ar","bn","it","ru"],"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProductsPageDto"}}}},"400":{"description":"Invalid input, or a rule of the shop refused it; the errorCode says which","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"429":{"description":"Rate limit reached (RATE_LIMIT_EXCEEDED); retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}}},"summary":"Browse the product catalog","tags":["Agent"]}},"/agent/payment-methods":{"get":{"operationId":"AgentController_getPaymentMethods","parameters":[{"name":"cartId","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPaymentMethodsDto"}}}},"404":{"description":"No such cart, product or order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"429":{"description":"Rate limit reached (RATE_LIMIT_EXCEEDED); retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}}},"summary":"Payment methods and the coins each one accepts; with a cartId, also which of them the cart can be paid with","tags":["Agent"]}},"/agent/cart":{"post":{"operationId":"AgentController_createCart","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentCartDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCartResponseDto"}}}},"400":{"description":"Invalid input, or a rule of the shop refused it; the errorCode says which","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"404":{"description":"No such cart, product or order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"410":{"description":"A product or amount is out of stock (CART_PRODUCT_OUT_OF_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"429":{"description":"Rate limit reached (RATE_LIMIT_EXCEEDED); retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}}},"summary":"Create a cart for a human shopper; returns a shareable storefront cart URL","tags":["Agent"]}},"/agent/checkout":{"post":{"description":"Crypto-only by design for now. Send payOption to choose between the crypto payments of GET /agent/payment-methods; each accepts its own coins. A payOption that a product in the cart rules out is answered with GIFT_PAYMENT_METHOD_NOT_ALLOWED, one that is temporarily unavailable with GIFT_PAYMENT_METHOD_UNAVAILABLE. Other payment methods (e.g. SEPA bank transfer) require a logged-in account and OTP step-up verification, so they cannot be initiated by an agent - hand the shopper the cartUrl to pay another way on the storefront. The shop may also refuse a large order (RISK_ORDER_LIMIT_EXCEEDED) or require an account for it (RISK_ORDER_LOGIN_REQUIRED); hand over the cartUrl in both cases.","operationId":"AgentController_checkout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCheckoutDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCheckoutResponseDto"}}}},"400":{"description":"Invalid input, or a rule of the shop refused it; the errorCode says which","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"403":{"description":"The order needs a customer account or exceeds the order limit (RISK_ORDER_LOGIN_REQUIRED, RISK_ORDER_LIMIT_EXCEEDED): hand over the cartUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"404":{"description":"No such cart, product or order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"410":{"description":"A product or amount is out of stock (CART_PRODUCT_OUT_OF_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}},"429":{"description":"Rate limit reached (RATE_LIMIT_EXCEEDED); retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentErrorDto"}}}}},"summary":"Create a crypto checkout for a cart; returns the hosted payment URL the human pays on","tags":["Agent"]}}},"info":{"title":"ACEB Agent API","description":"Public API for AI agents shopping on behalf of a human. No authentication and no API key - abuse is controlled by rate limits (HTTP 429 on excess). Flow: browse GET /agent/products, create a cart with POST /agent/cart and hand its cartUrl to your human, or go further with POST /agent/checkout and hand over paymentUrl - a hosted crypto payment page. GET /agent/payment-methods lists the crypto payments and the coins each accepts; send its id as payOption to choose one. The human always completes payment themselves; agents never handle funds. Checkout is CRYPTO-ONLY by design: other payment methods (e.g. SEPA bank transfer) require a logged-in account and OTP step-up verification, so agents cannot initiate them - shoppers who prefer another method should be handed the cartUrl and pay on the storefront. Large orders may be refused (RISK_ORDER_LIMIT_EXCEEDED) or need an account (RISK_ORDER_LOGIN_REQUIRED); hand over the cartUrl then too.","contact":{}},"tags":[{"name":"Agent"}],"servers":[{"url":"https://api.aceb.com"}],"components":{"schemas":{"CartModel":{"type":"object","properties":{"_id":{"type":"string","description":"Cart id"},"email":{"type":"string"},"orderId":{"type":"string"},"orderIds":{"type":"array","items":{"type":"string"}},"userNotifiedAt":{"format":"date-time","type":"string"},"products":{"type":"array","items":{"type":"string"}},"locale":{"type":"string"},"mergedIntoCartId":{"type":"string"},"assistantConversationId":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["_id","email","orderId","orderIds","userNotifiedAt","products"]},"AgentErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","example":404},"errorCode":{"type":"string","example":"CART_INVALID_FACE_VALUE","description":"Stable code of what was refused; the operation descriptions name the ones to expect"},"details":{"type":"object","additionalProperties":true,"description":"What the code refers to, e.g. the face values a product has after CART_INVALID_FACE_VALUE, or the suggested address after GIFT_EMAIL_DOMAIN_NOT_FOUND"},"message":{"description":"Validation messages of a rejected body; such an answer has no errorCode","type":"array","items":{"type":"string"}},"error":{"type":"string","example":"Bad Request"}},"required":["statusCode"]},"UpdateCartItemDto":{"type":"object","properties":{"cartId":{"type":"string","description":"Cart ID"},"productId":{"type":"string","description":"Product ID to update in cart"},"quantity":{"type":"number","description":"New quantity of the product","minimum":1},"selectedValue":{"type":"number","description":"New selected value for the product"},"productIndex":{"type":"number","description":"Index of the product in the cart products array. Use this to target a specific entry when the same product appears multiple times."},"email":{"type":"string","description":"Email of the user. Optional, used for cart recovery"}},"required":["cartId","productId","productIndex"]},"RemoveFromCartDto":{"type":"object","properties":{"cartId":{"type":"string","description":"Cart ID"},"productIndex":{"type":"number","description":"Product index in the cart"},"email":{"type":"string","description":"Email of the user. Optional, used for cart recovery"}},"required":["cartId","productIndex"]},"AgentOrderProductDto":{"type":"object","properties":{"productId":{"type":"string"},"quantity":{"type":"number"},"selectedValue":{"type":"number","description":"Face value per unit"},"currency":{"type":"string"},"total":{"type":"number","description":"Line total after discount"}},"required":["productId","quantity","selectedValue","currency","total"]},"AgentOrderStatusDto":{"type":"object","properties":{"orderId":{"type":"string"},"status":{"type":"string","enum":["new","pending","canceled","expired","paid","failed","completed","refunded"],"description":"Order lifecycle. 'pending' = awaiting payment; 'completed' = gift cards delivered to the order email."},"total":{"type":"number"},"totalNoDiscount":{"type":"number"},"currency":{"type":"string"},"paymentUrl":{"type":"string","description":"Hosted payment page. Only present while the order still awaits payment."},"products":{"type":"array","items":{"$ref":"#/components/schemas/AgentOrderProductDto"}},"createdAt":{"format":"date-time","type":"string"}},"required":["orderId","status","total","totalNoDiscount","currency","products","createdAt"]},"AgentProductAmountDto":{"type":"object","properties":{"min_face_value":{"type":"number","description":"Lowest face value of this amount or range"},"max_face_value":{"type":"number","description":"Highest face value; equal to min_face_value for a fixed amount"},"denomination_step":{"type":"number","description":"Step between the face values of a range; absent when any value in the range is allowed"},"stock_count":{"type":"number","nullable":true,"description":"Units left; null when the supplier does not count its stock"},"availability":{"type":"string","enum":["in_stock","out_of_stock","preorder","backorder"],"description":"Whether this amount can be bought now; out_of_stock for every amount of a card that is out of stock"},"discount":{"type":"number","description":"Customer discount in percent; 0 when the amount sells at or above face value"},"currency":{"type":"string","example":"USD"},"countries":{"description":"ISO 3166-1 alpha-2 codes the amount is sold for","type":"array","items":{"type":"string"}},"balance_check_url":{"type":"string"},"expiry":{"type":"string","description":"Validity of the card after purchase, as the supplier states it"}},"required":["min_face_value","max_face_value","availability","discount","currency","countries"]},"AgentProductCardDto":{"type":"object","properties":{"_id":{"type":"string","description":"Product id: the productId of carts and quotes"},"brand":{"type":"string","description":"Slug of the product page and of the MCP get_product tool"},"otherBrands":{"description":"Earlier slugs of the product","type":"array","items":{"type":"string"}},"title":{"type":"string"},"currency":{"type":"string","description":"The card currency as the supplier names it, else the one currency of the amounts; absent when the supplier names none and the amounts come in several currencies (then read each amount's)"},"countries":{"type":"array","items":{"type":"string"}},"products":{"description":"The amounts (face values) the product is sold in","type":"array","items":{"$ref":"#/components/schemas/AgentProductAmountDto"}},"logo":{"type":"string","description":"Image URL; empty when there is none"},"terms":{"type":"string"},"redeem_instructions":{"type":"string"},"description":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"isOutOfStock":{"type":"boolean","description":"Taken off sale by the shop"},"isComputedOutOfStock":{"type":"boolean","description":"Every amount is sold out"},"requiresAuth":{"type":"boolean","description":"Can only be bought with a customer account: hand the shopper the cart URL"},"blockedPaymentTiles":{"description":"Payment tiles of the storefront this product cannot be paid with","type":"array","items":{"type":"string"}},"metaTitle":{"type":"string"},"metaDescription":{"type":"string"},"h1":{"type":"string"},"reviewScore":{"type":"number","description":"Average review score, 0 when unrated"},"reviewCount":{"type":"number"},"brandFamilyId":{"type":"string","description":"Id shared by the products of one brand"},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"discount":{"type":"number","description":"Customer discount in percent of the best amount; 0 when the product sells at or above face value"}},"required":["_id","brand","otherBrands","title","countries","products","logo","terms","redeem_instructions","description","categories","isOutOfStock","isComputedOutOfStock","requiresAuth","reviewScore","reviewCount","faq","discount"]},"AgentProductsPageDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentProductCardDto"}},"total":{"type":"number","description":"Products that match, over all pages"},"page":{"type":"number","description":"Zero-based page: offset divided by limit"},"limit":{"type":"number"},"totalPages":{"type":"number"}},"required":["items","total","page","limit"]},"AgentAcceptedCoinDto":{"type":"object","properties":{"symbol":{"type":"string","example":"USDT"},"name":{"type":"string","example":"Tether"},"networks":{"description":"Networks the coin can be sent on. Absent when the hosted payment page lists them.","type":"array","items":{"type":"string"}}},"required":["symbol","name"]},"AgentPaymentMethodDto":{"type":"object","properties":{"id":{"type":"string","description":"For a crypto method: the value to send as payOption to POST /agent/checkout","enum":["classic","stablecoin","bank_transfer"]},"name":{"type":"string","example":"Stablecoins"},"agentCheckout":{"type":"boolean","description":"true: POST /agent/checkout can open this payment. false: only the human can, from the cartUrl on the storefront."},"coins":{"type":"array","items":{"$ref":"#/components/schemas/AgentAcceptedCoinDto"}},"apps":{"description":"Wallet and exchange apps the human can pay from","type":"array","items":{"type":"string"}},"currencies":{"description":"Currencies of a non-crypto method","type":"array","items":{"type":"string"}},"available":{"type":"boolean","description":"false when this method cannot be used now: it is temporarily unavailable (see note), or a product in the given cart cannot be paid this way (see blockedBy)."},"blockedBy":{"description":"Titles of the products in the cart that rule this method out","type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["id","name","agentCheckout","available"]},"AgentPaymentMethodsDto":{"type":"object","properties":{"methods":{"type":"array","items":{"$ref":"#/components/schemas/AgentPaymentMethodDto"}}},"required":["methods"]},"AgentCartItemDto":{"type":"object","properties":{"productId":{"type":"string","description":"Product ID"},"quantity":{"type":"number","description":"Quantity of the product","minimum":1},"selectedValue":{"type":"number","description":"Selected face value for the product"},"currency":{"type":"string","description":"Currency of the selected face value"},"country":{"type":"string","description":"Country the face value is sold for: one of the countries of its variant (a worldwide variant lists WW). Left out, the first variant in that currency. One the card is not sold for is refused with CART_INVALID_FACE_VALUE."}},"required":["productId","quantity","selectedValue","currency"]},"CreateAgentCartDto":{"type":"object","properties":{"cartId":{"type":"string","description":"Add to this cart instead of creating a new one"},"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentCartItemDto"}},"email":{"type":"string","description":"Shopper email. Optional, used for cart recovery"},"locale":{"type":"string","description":"Shopper locale for the cart page and emails","enum":["en","es","fr","de","ro","pt","zh","hi","ar","bn","it","ru"]}},"required":["items"]},"AgentCartResponseDto":{"type":"object","properties":{"cartId":{"type":"string","description":"Cart ID"},"cartUrl":{"type":"string","description":"Storefront URL that opens this cart - hand it to the shopper"}},"required":["cartId","cartUrl"]},"AgentCheckoutDto":{"type":"object","properties":{"cartId":{"type":"string","description":"Cart ID (from POST /agent/cart)"},"email":{"type":"string","description":"Email the gift cards are delivered to"},"currency":{"type":"string","description":"Currency to charge (e.g. EUR, USD)"},"giftEmail":{"type":"string","description":"Deliver the gift to this email instead"},"giftMessage":{"type":"string","description":"Gift message"},"couponCode":{"type":"string","description":"Coupon code"},"paymentMethod":{"type":"string","description":"Payment method. Defaults to 'crypto' - currently the only method an agent checkout can complete; others require a logged-in account + OTP step-up and are rejected. The field exists so future agentic methods (e.g. cards) can be requested explicitly.","enum":["crypto","bank_transfer"],"default":"crypto"},"payOption":{"type":"string","description":"Which crypto payment to open: an id from GET /agent/payment-methods. Each one accepts its own coins. Left out, the server picks the first one every product in the cart can be paid with.","enum":["classic","stablecoin"]},"locale":{"type":"string","description":"Shopper locale for order emails and redirect pages","enum":["en","es","fr","de","ro","pt","zh","hi","ar","bn","it","ru"]}},"required":["cartId","email","currency"]},"AgentCheckoutResponseDto":{"type":"object","properties":{"orderId":{"type":"string","description":"Order ID"},"paymentUrl":{"type":"string","description":"Hosted crypto payment page - hand it to the shopper; the order completes when they pay there"},"payOption":{"type":"string","description":"The crypto payment that was opened. GET /agent/payment-methods lists the coins it accepts.","enum":["classic","stablecoin"]},"cartUrl":{"type":"string","description":"Storefront URL of the cart - the shopper can review/edit it there, or pay with a non-crypto method (e.g. SEPA bank transfer, which needs a logged-in account + OTP and cannot go through this API)"}},"required":["orderId","paymentUrl","cartUrl"]}}}}