check_listing

tickets.xp/xp-tickets · Verify this 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