Return server version, active host, and configuration locations.

The active_host field reflects what default_host is set to (or what would be used when a tool call omits the host parameter). When set to "production", the response includes a warning field — real money is at stake on bid/buy operations.

List every configured host with its status (default flag and cert availability).

Useful for diagnosing why a tool call against a particular host might fail before you make the call.

Search eBay items via the Browse API.

Args: query: keyword search string. Required. category_id: numeric eBay category ID to restrict the search. condition: one of NEW, LIKE_NEW, NEW_OTHER, USED_EXCELLENT, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE, FOR_PARTS_OR_NOT_WORKING, MANUFACTURER_REFURBISHED, CERTIFIED_REFURBISHED, or several other refurbished tiers. Case-sensitive. min_price: minimum item price (in currency). max_price: maximum item price (in currency). currency: ISO currency code for the price filter (default "USD"). sort: one of "best_match" (default), "price_asc", "price_desc", "newly_listed", "ending_soonest". limit: number of hits per page. Default 20, hard cap 200. offset: pagination offset. marketplace: eBay marketplace ID (default "EBAY_US"). Other examples: "EBAY_GB", "EBAY_DE", "EBAY_IT". host: which configured host to use ("sandbox" or "production"). If omitted, uses the config's default_host.

Returns: dict with: - host: which host was actually targeted - total: total matching items per eBay - limit, offset, next_offset (None when there's no next page) - hits: list of item summaries (item_id, title, price, currency, condition, seller, image_url, ends_at, buying_options, web_url, bid_count if applicable)

Fetch full details for a single eBay item by ID.

Args: item_id: the eBay item ID (e.g., "v1|353528728623|0"). Get these from search() results. marketplace: eBay marketplace ID (default "EBAY_US"). host: which configured host to use. Defaults to config's default_host.

Returns: Full item dict including description, shipping options, seller details, return terms, item location, and the standard summary fields. If the item doesn't exist or has ended, returns {"item_id": item_id, "host": host, "missing": true}.

Return the authenticated user's watched items.

Uses Trading API GetMyeBayBuying with the WatchList container. Requires that the user has authenticated via start_user_auth + complete_user_auth for the chosen host.

Args: limit: items per page (1-200). Default 100. offset: pagination offset. Trading API pages from 1; we translate. host: configured host name. Defaults to default_host.

Returns: dict with host, container, total, limit, offset, and hits (a list of item summaries: item_id, title, price, currency, ends_at, bid_count, seller, web_url, listing_type, quantity_available).

Return auctions where the user has a currently-active bid.

Trading API GetMyeBayBuying.BidList. Includes both winning and outbid items still in their bidding period.

Same response shape as get_watchlist. Empty hits + total=0 means you have no active bids.

Return items the user won at auction or bought via Buy It Now.

Trading API GetMyeBayBuying.WonList. This is your effective "purchase history" for the eBay-native default lookback window (eBay shows the last 30 days by default; older items roll off the WonList container).

Same response shape as get_watchlist.

Return auctions where the user bid but did not win.

Trading API GetMyeBayBuying.LostList. Default lookback ~30 days; older items roll off.

Same response shape as get_watchlist.

Add an item to the authenticated user's watchlist.

Trading API AddToWatchList. Fully reversible — call remove_from_watchlist with the same item_id to undo.

Args: item_id: numeric eBay item ID (from search, get_item, etc.) host: configured host. Defaults to default_host.

Returns: dict with host, item_id, added: True, and watch_list_count (total items in the watchlist after the operation). Raises ValueError on empty item_id. On eBay-side errors (item ended, already watched, etc.) the Trading API raises TradingApiError with details.

Remove an item from the authenticated user's watchlist.

Trading API RemoveFromWatchList. Fully reversible — call add_to_watchlist with the same item_id to undo.

Args: item_id: numeric eBay item ID currently on the watchlist. host: configured host. Defaults to default_host.

Returns: dict with host, item_id, removed: True, and watch_list_count (total items in the watchlist after the operation). Raises ValueError on empty item_id. eBay-side errors (item not on watchlist, etc.) surface as TradingApiError.

Begin OAuth2 user authentication for buyer-side eBay operations.

Watchlist, MyeBay reads, bidding, and buying all require a user token. This tool returns an auth_url for you (the human) to open in a browser. After signing in and granting permissions, eBay redirects to the configured redirect_uri with a code query parameter — pass that to complete_user_auth to finalize.

Most workflows only run this once per host; tokens persist 18 months and auto-refresh.

Args: host: which configured host to authenticate against. Defaults to config's default_host.

Returns: dict with host, auth_url, state, and instructions. The auth_url is what the human needs to open; the state is round-tripped to verify the callback genuinely came from this flow.

Finish OAuth2 user auth by exchanging the authorization code for tokens.

The code is the value of the code query parameter in the URL eBay redirected to after start_user_auth's auth_url. Optionally pass state to verify against what start_user_auth issued (CSRF defense).

Args: code: the authorization code from eBay's redirect URL. state: optional — the state value from the redirect URL. If provided, must match what start_user_auth stored. Mismatch returns a structured refusal payload. host: which configured host to authenticate against. Defaults to config's default_host. Must match the host used in start_user_auth.

Returns: On success: {host, authenticated: true, access_expires_at, refresh_expires_at} On state mismatch: {refused: true, reason: "state_mismatch", host, message: ...}

Place a proxy bid on an eBay auction.

Trading API PlaceOffer with Action=Bid. eBay treats max_bid_amount as a proxy ceiling — it bids the minimum needed to outbid the current high bidder, and continues raising up to max_bid_amount as competing bids come in.

PRODUCTION HOST WARNING: when the active host is "production", a successful call commits real money on eBay. Inspect server_info() or list_hosts() before committing.

Args: item_id: numeric eBay item ID. Get from search() or get_item(). max_bid_amount: the proxy bid ceiling in currency. Must be > 0. confirm_amount: must equal max_bid_amount exactly. The repeated dollar amount is a safety gate against typos. quantity: number of units (default 1; only relevant for multi-quantity auctions). currency: ISO currency code matching the listing (default "USD"). Must match the listing's currency or eBay refuses. max_bid_override: optional ceiling that authorizes amounts above the $500 per-call safety cap. Pass a value >= max_bid_amount to bypass the cap for this call. Lower values are refused. host: configured host name. Defaults to default_host. The active host (sandbox vs production) is surfaced in the response.

Returns: On success: dict with host, item_id, action="Bid", amount, currency, placed=True, current_price, minimum_to_outbid, high_bidder, and (on production) a warning field. On safety-gate failure: structured refusal payload (refused=True, reason, message, plus the offending values). Raises ValueError on empty item_id, non-positive amounts, etc. On eBay-side errors (listing ended, currency mismatch, insufficient bid, etc.) raises TradingApiError.

Purchase a Buy It Now listing immediately at the listed price.

Trading API PlaceOffer with Action=Purchase. The buyer commits to pay the listing's BIN price; eBay creates the order on success.

PRODUCTION HOST WARNING: when the active host is "production", a successful call commits real money on eBay. Inspect server_info() or list_hosts() before committing.

Args: item_id: numeric eBay item ID. Get from search() or get_item(). confirm_amount: must equal the listing's Buy-It-Now price exactly. The repeated dollar amount is a safety gate against stale prices or typos. Look up the current price with get_item() right before calling. quantity: number of units to purchase (default 1). Multi-quantity BIN listings can have a per-buyer limit; eBay rejects with TradingApiError if violated. currency: ISO currency code matching the listing (default "USD"). max_bid_override: optional ceiling that authorizes amounts above the $500 per-call safety cap. Pass a value >= confirm_amount to bypass the cap for this call. host: configured host name. Defaults to default_host.

Returns: On success: dict with host, item_id, action="Purchase", amount, currency, quantity, placed=True, and (on production) a warning. On safety-gate failure: structured refusal payload. Raises ValueError / TradingApiError as in place_bid.

Submit a Best Offer on a listing that has Best Offer enabled.

Trading API PlaceOffer with Action=BestOffer. The seller can accept, counter, or decline; this call only places the offer.

PRODUCTION HOST WARNING: when the active host is "production" and the seller accepts, the offer becomes a binding sale at the offer amount.

Args: item_id: numeric eBay item ID. Must have Best Offer enabled — check buying_options on get_item() output for "BEST_OFFER". offer_amount: the price the buyer offers, in currency. Must be > 0. Many sellers configure auto-decline below a threshold. confirm_amount: must equal offer_amount exactly. Safety gate. quantity: number of units the offer covers (default 1). currency: ISO currency code matching the listing (default "USD"). max_bid_override: optional ceiling that authorizes offer amounts above the $500 per-call safety cap. Pass a value >= offer_amount to bypass. host: configured host name. Defaults to default_host.

Returns: On success: dict with host, item_id, action="BestOffer", amount, currency, quantity, placed=True, optionally best_offer_id (for follow-up via Trading GetBestOffer / Accept flows), and (on production) a warning. On safety-gate failure: structured refusal payload. Raises ValueError / TradingApiError as in place_bid.