XP Tickets MCP Server

Poll the current status and action feed for the listing tied to this call's correlation id. IDENTITY: the correlation id is never a tool argument. It must ride the ``X-XP-Correlation-Id`` HTTP header on every MCP request, exactly like on every other tool call for this job. A missing/invalid header returns a structured error (below) instead of failing the call -- this tool is open-world (no bearer/OAuth needed); holding the correlation id (an unguessable v4 uuid) is itself the access control. ARGS since: the ``cursor`` value returned by the previous call for this same correlation id. Omit (or pass null) on the first call to fetch the full action feed from the beginning. Must be >= 0; a negative value returns ``{"error": "invalid_since"}``. POLL LOOP: store ``cursor`` per correlation id in your own cache/store, send it back as ``since`` on the next call, and render only the new ``actions`` entries onto your own timeline -- the array already excludes anything at or before ``since`` and is empty when nothing changed. ``listing`` is a snapshot for cheap "current state" display only (quantity, bid count, bucket, ...); do not diff it yourself for history -- ``actions`` is the exact, ordered record (a bid placed and rescinded between two polls still yields both events). RESULT SCHEMA (``found: false`` -> every other field is null/absent; an unrecognized correlation id is not an error, just an empty result):: { "correlation_id": "<uuid>", "found": true, "verified": true, # identity confirmed when the listing was created "event_id": 406, # last event this correlation looked at "listing": { # null until a listing exists for this id "swap": "d5b03i1rbqqa", # public listing identifier (sell/checkout URLs) "created_at": "2026-08-12T14:00:00+00:00", "status_bucket": "open", # see BUCKETS below "event_id": 406, "quantity": 2, "bid_count": 3, "top_bid_amount": 12000, # cents, open bids, null if none "accepted_bid_amount": null, # cents, set once a bid is accepted "sold": false, "last_activity_at": "2026-08-12T14:05:00+00:00" }, "actions": [ # everything after `since`, oldest first, [] if nothing new {"id": 91234, "event": "listing_created", "at": "2026-08-12T14:00:00+00:00"}, {"id": 91288, "event": "bid_placed", "at": "2026-08-12T14:03:10+00:00", "amount": 12000} ], "cursor": 91301, # send back as `since` on the next call "actions_truncated": true # present+true only when 50+ new rows; call again with `cursor` to page } BUCKETS (listing.status_bucket) open - accepting bids, none accepted yet awaiting_tickets - a bid was accepted; seller hasn't transferred tickets yet buyer_has_tickets - tickets transferred; seller payout not yet finalized seller_payout - funds are ready to release to the seller zombies - stalled, no forward progress -- needs attention closed - terminal: cancelled, expired, or fully settled EVENT VOCABULARY (actions[].event; only bid/sale events carry `amount`, in cents) listing_created, bid_placed, bid_rescinded, bid_accepted, bid_rejected, tickets_transferred, funds_claimed, listing_cancelled, listing_expired, sale_completed NOTE: no separate payout-completion signal exists -- the agent-forward payout rail is retired; sellers claim funds normally (funds_claimed). FAILURES: this tool never raises and never returns an auth error (401). {"error": "missing_correlation_header", "message": "..."} - header missing/invalid {"error": "invalid_since"} - since < 0 {"error": "status_unavailable"} - backend down/slow/non-200

Use when the user wants to sell tickets they hold on the XP marketplace -- 'sell my two seats for Friday', 'list section 104 row C', 'put my tickets up'. Creates the listing that buyers (other fans on XP) then make an offer on; the seller answers those with accept_offer and reject_offer. Tickets are not transferred now -- transfer happens after an offer is accepted. Ask the seller whether the seats are accessible (ADA), obstructed view or standing room only: all three are required, never assumed. Two-phase: confirm=false previews so the section, row, seats and those three can be read back to the user, confirm=true creates it. A new listing is REVIEWED before it goes live. The result carries listing_state -- live, in_review or not_accepted -- and only `live` means buyers can see it. Do not tell the user their tickets are for sale unless it says live. Requires auth.

If the listing has sold and is awaiting the seller's ticket transfer, the result carries the transfer instructions and remaining obligation -- surface those first, ahead of anything else. From XP's connected resale + primary order book. Use when an authenticated seller wants to poll their listing on XP — open bids, state, seats — before deciding to accept or reject an offer (e.g. 'any new bids on my tickets to the season opener?'). Surfaces the seller view of the live offer book. After create_listing, call it to confirm what XP stored (seats, disclosures) and whether buyers can see it: trust visible_to_buyers, not the state. Open-bid amounts are dollars in amount_usd. When is_seller is true, each offer includes actions mapping to accept_offer and reject_offer. Requires auth and read:bids scope. Do not use for casual ticket buyers; this is the seller-side and power-user marketplace surface. For standard ticket purchases, use `search_events` and `get_ticket_listings`.

Creates a STANDING OFFER -- that is the term to use when speaking to the user; the tool keeps `standing_bid` only because the stored records do. Use when the user wants to make an offer at their own price across one or more events and sections and wait for it to fill, rather than paying an asking price now -- e.g. 'offer 80 a seat for any of these nights', 'let me know if something in 104 comes up at my number'. The offer rests on XP's live offer book and fills itself when a matching fan listing appears, so it needs no listing to exist yet. Worth knowing before resting one: when a matching listing is already open, an offer on it (make_offer_on_listing) gets an answer the user will see -- accept, reject or counter -- while a standing offer waits for supply that may never arrive. Check what is open first (list_open_listings, or get_market_read for one event). Both are valid; resting a price where nobody is selling yet is what this tool is for. Say which you did. Two-phase: call with confirm=false to preview the total commitment, then confirm=true once the user agrees. Price is whole dollars per ticket -- XP refuses cents so every fill passes per-ticket validation. Fills take whole lots and cannot strand a remainder. Requires auth.

Use when the user asks about one specific standing offer on the XP marketplace -- whether it filled, how much of it is left, or 'did that offer get my tickets'. Returns the offer at any status along with the fills it has taken, so it answers for filled and rescinded offers that `list_my_standing_bids` does not show. Requires auth.

Use when the user asks what offers they have resting on the XP marketplace, what they are waiting on, or before they make an offer so you do not stack a duplicate. A standing offer buys at the user's price whenever a matching fan listing appears, without them watching for it. Live offers only -- filled ones have become tickets (`get_my_tickets`) and rescinded ones are history; both stay reachable by id through `get_standing_bid`. Requires auth.

From XP's connected resale + primary order book. Use when an authenticated buyer wants a fan listing outright at the seller's published asking price, rather than negotiating -- 'buy it now', 'take it at the ask', 'just buy me those tickets to the game'. Only listings that carry an asking price can be bought this way; for one without an ask, use make_offer_on_listing. Two-phase: confirm=false previews the total so it can be read back to the user, confirm=true buys. A confirm here completes the sale immediately -- the money leaves the caller's XP USDC balance and the seller is committed. Pays from the caller's XP USDC balance; the x402 rail does not apply to fan listings, only to buy_tickets. Requires auth.

Use when the user wants tickets to an event on the XP marketplace (connected order book). Four payment rails are supported. Use 'stripe_link' (the default — omit `rail` to get it) unless the user asks for another: pay by CARD on a Stripe-hosted Checkout page; the preview returns payment_link and checkout_session_id — open the link for the user, then call again with confirm=true and checkout_session_id; the result includes stripe_payment_intent. Other rails, by name only: 'privy' (server-signed USDC transfer from the user's delegated Privy embedded wallet), 'x402' (agent-signed Solana USDC transfer via the x402 protocol — use only if the caller can build and sign Solana x402 'exact' payloads), and 'mpp' (pay by CARD with a Stripe Shared Payment Token over the Machine Payments Protocol binding; present the credential in params._meta['org.paymentauth/credential'], or in the payment_credential argument when your client cannot send _meta). Requires `write:tickets` scope (and `read:account` for the balance preflight when using granular scopes). Call once with confirm=false to preview the total, then call again with confirm=true after the user explicitly approves.

Use when a seller wants to remove their own listing from the XP marketplace -- 'take my listing down', 'delist those', 'I sold them elsewhere', 'cancel that listing'. Closes the listing so buyers can no longer make an offer on it. Every open offer on the listing is REJECTED and those buyers are notified that it was removed -- say so before committing, since someone waiting on an answer gets a no. Cannot be used once the seller has accepted an offer: that is an agreed sale, and XP support handles it from there. Two-phase: confirm=false previews, confirm=true removes it. Cannot be undone -- relisting means calling create_listing again. Requires auth; works only on the caller's own listing.

From XP's connected resale + primary order book. Two-phase write on the XP live offer book. Use when an authenticated buyer wants to rescind their outstanding offer on an XP marketplace listing (e.g. 'cancel my offer to make an offer at a lower price', 'pull my bid'). Call with `confirm=False` first to preview which offer will be rescinded; call with `confirm=True` only after the user explicitly approves. Pass bid_uuid from make_offer_on_listing (or the buyer swap id from the same response; the server resolves it). Only confirm=True submissions return success=true. Requires auth and write:bids scope. Do not use for browse / discovery; this is a marketplace transaction tool that mutates an active bid. For standard buy-now ticket purchases without a bid in flight, use `search_events` and `get_ticket_listings`.

Use when the user wants to understand what an event is trading at, not just browse rows. Returns the cheapest fee-inclusive price in each area of the building from XP's connected order book, ordered by price, plus the fan listings open to offers. Lead with the cheapest fan ask when there is one: it is a price the user can offer against, so the user can make an offer instead of paying the ask. Do not describe the market with averages, medians, or maximum asks.

Use when the user is shopping and might make an offer rather than pay the asking price. Searches XP events and returns both sides of the connected order book per event: the fee-inclusive marketplace get-in price from resale + primary inventory, and whether fans are selling into that event, with their cheapest ask. Prefer this over search_events whenever price matters, e.g. 'tickets to the season opener' or 'cheap seats near me' when the user might make an offer. Do not use for scores, news, or standings.

From XP's connected resale + primary order book. Use when a listing identifier is in hand and the user wants the full record for one open listing on the XP marketplace before they make an offer. Returns one row from the live offer book. Requires auth and read:bids scope. Do not use for casual ticket buyers; this is the seller-side and power-user marketplace surface. For standard ticket purchases, use `search_events` and `get_ticket_listings`.

From XP's connected resale + primary order book. Use when the user wants to browse the live offer book of listings open on XP (e.g. 'what's open near me this weekend', 'open listings with active offers'). Filterable by event, performer, and amount. Requires auth and read:bids scope. Do not use for casual ticket buyers; this is the seller-side and power-user marketplace surface. For standard ticket purchases, use `search_events` and `get_ticket_listings`.

ACCEPTING SELLS TO A BUYER AND STARTS A CLOCK: the offer comes from a buyer on XP, not from XP. Once it's accepted, the seller must transfer the tickets through XP to that buyer by a deadline XP sets at that moment. Missing it can cancel the sale and forfeit the payout. The deadline is per sale, not a fixed window -- do not quote a countdown of your own. The accept result carries the real one, or says plainly when XP has not set it yet; pass that on. From XP's connected resale + primary order book. Two-phase write on the XP live offer book. Use when an authenticated seller wants to accept a specific bid on their listing (e.g. 'accept the $200 offer on my tickets'). Call with `confirm=False` first to preview which offer will be accepted; call with `confirm=True` only after the user explicitly approves. Acceptance is irreversible. Do not use without the two-phase preview-then-confirm flow. Only confirm=True submissions return success=true. Requires auth and write:listings scope. Do not use for casual ticket buyers; this is the seller-side and power-user marketplace surface. For standard ticket purchases, use `search_events` and `get_ticket_listings`.

Use ONLY when the user explicitly asks whether they are signed in to the XP marketplace (e.g. 'am I logged in?', 'am I connected to my tickets?'), or after a protected tool already returned AUTH_REQUIRED and the user wants the current state re-checked. Do NOT call this as a preflight before account / my tickets / wallet / favorites / referral / order tools — calling auth_status first swallows the 401 those tools would emit on the connected order book and prevents the MCP client from triggering OAuth. Always call the requested protected tool directly; the client will start sign-in on 401. Read-only. Returns authenticated boolean, tier roles, and a wallet flag — never raw tokens.

Use when an authenticated user wants to see the bids they have placed on the XP marketplace — e.g. 'show my bids', 'what offers did I make?', 'tickets to the shows where I'm bidding', 'did any of my bids settle?'. Returns bids classified as open or completed using the same outcome engine as the admin reporting page; rejected/lapsed/refunded bids are hidden. Paged: returns 25 by default, up to 200 with `limit`, and `offset` to continue. `pagination.total` counts only the bids the user can actually see, so when has_more is set say they are seeing a page rather than every bid they have. Read-only. Requires OAuth.

Use once the user has settled on an event, before quoting prices, to see what they already told XP: budget per ticket, quantity, date flexibility, and any saved notes. Stops you asking twice for something they said before, e.g. re-asking a budget right before you help them make an offer on the XP marketplace. Read-only: nothing said in this conversation is stored, so a new budget only persists if it becomes a resting commitment -- see create_standing_bid. Use saved notes to shape what you say, never read them back verbatim.

Use when an event ID is in hand and the user wants the full event card before browsing tickets to that event — venue, performers, fee-inclusive price preview, images. Pulls from the XP marketplace catalog. Cache the result for the conversation rather than re-calling for the same event_id. Do not use to list ticket inventory; `get_ticket_listings` is the right tool for seat-level data.

Use when the user wants to find live events on XP — concerts, sports, theater — by performer, team, venue, city, or keyword (e.g. 'tickets to the season opener', 'shows near me this weekend'). Surfaces the connected order book of resale + primary inventory in one feed. Do not use for scores, news, standings, or non-ticketed listings; use a web tool for those.

Use when an authenticated user wants the performers they've favorited on the XP marketplace (e.g. 'show my favorites going to a game this weekend', 'who am I following on near me events?'). Read-only; requires auth and read:account scope. Pair with `search_events` to find tickets to favorite performers on the connected order book. Paged: returns 25 by default, up to 200 with `limit`, and `offset` to continue. Some accounts follow thousands of performers, so when pagination.has_more is set say the user is seeing a page rather than everyone they follow.

Paged: a large book comes back one page per lifecycle category, and the result carries pagination totals per category. When has_more is set, say so -- never present a page as the whole book -- and either page on with offset or narrow with state_category. From XP's connected resale + primary order book. Use when an authenticated seller wants to see their listings on the XP marketplace bucketed by lifecycle (e.g. 'show my tickets I'm selling', 'what's open in my seller queue'). Surfaces seller-side categories that gate next steps in the live offer book. Requires auth and read:bids scope. Do not use for casual ticket buyers; this is the seller-side and power-user marketplace surface. For standard ticket purchases, use `search_events` and `get_ticket_listings`.

From XP's connected resale + primary order book. Two-phase write on the XP live offer book. Use when the user wants to make an offer on an open XP listing (e.g. 'make an offer of $50 on this'). Call with `confirm=False` first to preview the fee-inclusive total (no bid placed); call with `confirm=True` only after the user explicitly approves the previewed amount. Only confirm=True submissions return success=true. Do not use without the two-phase preview-then-confirm flow. Requires auth and write:bids scope. Do not use for browse / discovery; this is a marketplace transaction tool that places real money at risk. For standard buy-now ticket purchases without a bid, use `search_events` and `get_ticket_listings`.

Use when the user says they are not interested in a listing on the XP marketplace, wants to stop seeing it, or wants a muted one back -- e.g. 'hide this one', 'stop showing me that', 'unmute that listing', or after deciding not to make an offer on it. Muting affects only this user's view of the live offer book. It does not close the listing, withdraw an offer, or change anything for the seller or other buyers. Sets the state you pass rather than toggling, so repeating a call is safe. Requires auth.

Use when the user asks what they have hidden or muted on the XP marketplace, or before muting so you do not tell them you muted something that was already muted. Returns the listing identifiers this user has muted. Muting is per-user and never touches the listing itself. It hides the listing on xp.tickets; list_open_listings and get_market_read do NOT filter muted listings, so read this list before showing the user listings to make an offer on. Requires auth.

Get the status of one of the authenticated user's orders on the XP marketplace, by the order_uuid that buy_tickets returned. Use right after a purchase, or when the user asks about a specific order -- 'did that go through', 'is my order confirmed', 'when do my tickets arrive'. Returns status, vendor fulfilment status, delivery method, in-hand date, event, seats and fee-inclusive total. Money is in dollars. Requires auth; only the caller's own orders are visible. Without an order_uuid, use `get_my_orders` for the recent list.

Show the authenticated user their own orders on the XP marketplace and where each one stands. Use when the user asks about a purchase they already made -- 'where is my order', 'did my tickets go through', 'what did I buy for Saturday', 'when do my tickets arrive'. Newest first; returns status, vendor fulfilment status, delivery method, in-hand date, event, seats and fee-inclusive total. Money is in dollars. Requires auth. Do NOT use for tickets already delivered to the account -- `get_my_tickets` is the direct answer there. Not for seller-side listings (`list_my_listings`) or offers the user placed (`get_my_bids`).

Find a performer (artist, team, comedian) on the XP marketplace by name. Use when the user names a specific performer (e.g. 'tickets to Taylor Swift', 'Lakers season opener', 'Phish tour dates'). Returns performer cards from the XP catalog — not events. Pair with `search_events` once a performer is selected to surface their upcoming events on the connected order book. Do not use for general 'events near me' queries; `search_events` handles those better.

Use when the user asks whether prices for an event are rising or falling, whether to buy now or wait for a price drop, or what an event has been doing lately. Returns the daily closing get-in price on the XP marketplace, one point per day, oldest first, with the fee-inclusive per-ticket price in dollars. This is the asking side over time -- what tickets actually sold for is `get_recent_sales`, and the two must not be conflated. An empty history is a real answer and a common one: XP records history only for events someone is tracking, so a quiet event has no line rather than a flat one.

Use when the user asks what tickets actually sold for on an event, or before claiming nothing has traded. Returns recent completed deals from the XP marketplace with the per-ticket price and how long ago each cleared. An empty result is a real answer: no verified transfers in the window. Useful before deciding whether to make an offer or wait for a price drop. One sale is one sale -- do not generalise from a single clear.

Use when an authenticated user wants their XP marketplace referral kickback totals and rows (e.g. 'how many friends bought tickets to the season opener through my link?', 'show my kickbacks'). Returns direct/indirect referral counts, total spend and total kickback in dollars, and per-referral rows from the XP marketplace. Read-only; requires auth and read:account scope.

From XP's connected resale + primary order book. Two-phase write on the XP live offer book. Use when an authenticated seller wants to reject a specific bid on their tickets to a listing (e.g. 'reject the lowball offer on my tickets'). Call with `confirm=False` first to preview which offer will be rejected; call with `confirm=True` only after the user explicitly approves. Do not use without the two-phase preview-then-confirm flow. Only confirm=True submissions return success=true. Requires auth and write:listings scope. Do not use for casual ticket buyers; this is the seller-side and power-user marketplace surface. For standard ticket purchases, use `search_events` and `get_ticket_listings`.

Use when the user no longer wants a standing offer resting on the XP marketplace -- 'cancel that standing offer', 'stop waiting on those', or they would rather make an offer on something open instead. Closes it to new fills. Fills it already took are completed purchases and are not undone. Two-phase: confirm=false previews, confirm=true commits. Requires auth.

Use when the user asks where a section is, what the venue looks like, or wants to see the layout before picking seats on the XP marketplace -- 'where is 104', 'show me the map', 'is that behind the stage'. Returns the venue seating chart as an image. This is the venue LAYOUT -- where each section sits in the building. It is NOT a photograph of the view from a seat and must never be described as one. Not every venue has a chart; when one is missing say so plainly, and note that the section and row from `get_ticket_listings` still describe the seats exactly. No sign-in required.

Use when the user wants to see ticket options and fee-inclusive prices for a specific XP event after `search_events` (e.g. 'cheap seats', 'parking for the game'). Pulls the live offer book of resale + primary inventory. Do not use before an event has been resolved — call `search_events` or `get_event_details` first. Prices are dollars: each ticket row carries per_ticket_usd. error_code NO_INVENTORY means the event is real but has nothing listed right now: do not retry, give the user the event page or another date.

Show the authenticated user the tickets currently delivered to their XP marketplace account, all backed by XP's Quality XPerience Guarantee. Use when the user says 'my tickets', 'what tickets do I have', 'pull up my seats for tonight', or asks about an upcoming event they've already bought. Surfaces only delivered tickets — pending swaps and seller-side listings appear in `list_my_listings`. Requires auth. Do not use to list past orders or browse the marketplace; this is strictly delivered tickets on the user's account.

Pull the authenticated user's XP marketplace account card — profile, wallet, email, name, order history, and referral stats. Use when the user asks 'what have I bought from XP', 'my account', 'my tickets to past games', 'my orders', 'my referral link', or 'how much have I spent'. Returns the profile shown on the XP account page. Read-only; requires auth. Do not use for tickets currently delivered to the account; `get_my_tickets` is more direct.

Pull full venue info from XP plus the upcoming-events calendar at that venue, with live pricing from the connected order book of resale + primary inventory. Use after `search_venues`, or when the user asks 'what's coming up at the venue', 'what's playing at the Garden', 'shows at the venue this month'. Returns the upcoming-events feed so the agent can offer next-step `get_ticket_listings` calls. Do not use to fetch ticket inventory for a specific event; `get_ticket_listings` is the right tool for seat-level data.

Use when the user wants to find a venue by name, city, or area on XP (e.g. 'venues near me', 'arenas in Brooklyn', 'what's at the venue level downtown'). Returns venue records from the XP marketplace catalog — not tickets. Do not use to answer ticket-price questions once the event is known; call `get_ticket_listings` instead.

Use when an authenticated user wants their XP marketplace Privy embedded-wallet address and USDC balance (e.g. 'what's my wallet for tickets to tonight?', 'how much USDC before I make an offer?'). Returns the wallet address, a `wallet_connected` flag, and the USDC balance — never the raw bearer token. Read-only; requires auth and read:account scope. Used to fund offers on the live offer book.