One host, two API contracts
The compatibility routes preserve V1 request parameters, complete retail results, product fields, substring search, sorting, JSON envelopes and CSV formats. The V2 routes provide explicit pagination, richer search and dataset health.
| Connection setting | How it works |
|---|---|
| Existing production hostname | https://tradepost.bidzone.com. Clients keep this hostname. Check /api/v2/deployment for the active implementation; V1 continues serving until V2 snapshots are ready. |
| This host | https://YOUR-HOST. A trycloudflare.com address is a temporary review host, not permanent bot hosting. |
| Existing requests | Use the original /api/products, /api/market/… and /api/account/… paths. Legacy aliases and bulk manifests remain available. |
| New requests | Use the /api/v2/… reference below. Both contracts read the same stored snapshots. |
| Public access | No password or API key is required. |
| Private access | Use the existing Authorization: Bearer … header. Read /api/v2/account/dashboard?view=full for all orders, payments, shipments and addresses in one snapshot. Full details require pii:read. See account retrieval and field meanings. Imported V1 credentials retain their tokens, expiry, permissions and redacted IDs; revocation remains enforced. |
Existing bot credentials are separate from the application publishing secret. The read examples below do not need publishing access.
The HTTP library can stay the same. Existing clients do not have to adopt V2 pagination or change parsers to use the compatibility routes. Moving an existing client to /api/v2/… is optional and requires adopting that contract.
Quick start: public reads
Set the base URL once. Use the origin only, without /api at the end. The examples below use the host serving this page.
export TRADEPOST_V2_BASE_URL="__ORIGIN__"
# Versions, source timestamps and collection health
curl --fail-with-body "$TRADEPOST_V2_BASE_URL/api/v2/status"
# Market search; parameters are URL-encoded for you
curl --fail-with-body --get "$TRADEPOST_V2_BASE_URL/api/v2/market/products" \
--data-urlencode 'q=vault' \
--data-urlencode 'min_sales=1' \
--data-urlencode 'limit=50'
# Comparable retail products with recent sales
curl --fail-with-body --get "$TRADEPOST_V2_BASE_URL/api/v2/retail/products" \
--data-urlencode 'q=vault' \
--data-urlencode 'view=comparisons' \
--data-urlencode 'min_sales=1'
Run the included Python example
Python 3.11 or newer, with no extra packages. It checks source age, pins the dataset version, reads every matching page and prints the result after the read completes.
curl --fail-with-body "$TRADEPOST_V2_BASE_URL/examples/tradepost_v2.py" \
--output tradepost_v2.py
python3 tradepost_v2.py --dataset market --query vault
python3 tradepost_v2.py --dataset retail --query '151 etb'
The client is a working starting point, not an autonomous trading bot. It only reads data. Its base URL comes from TRADEPOST_V2_BASE_URL; it never reads or changes an existing V1 configuration.
A complete bot update
- Check status. Read
/api/v2/statusand selectdatasets.marketordatasets.retail. Check its collection time and the relevant collection operation. - Compare versions. If the version and your query/policy are unchanged, reuse your saved catalog. Polling status every 5–15 minutes is a reasonable starting schedule for snapshots collected about twice daily.
- Pin and stage. Send that version on every public page, or download a complete versioned export into a temporary file. Market and retail have independent versions.
- Validate. Check the final page/export completed, confirm source age, and handle absent prices explicitly. Match exact product IDs plus category/package/edition details.
- Replace your cache. Only publish the staged result to the bot after the complete run succeeds. On an unavailable/changing snapshot, discard the partial run and restart.
Use public tradepost_id and market category as identity. Titles are preserved but are not unique. A case, single pack and regional edition can have similar names and different prices.
Endpoint reference
All paths are relative to the V2 base URL. Public routes accept GET and HEAD; private account reads accept GET. The API is read-only: it cannot buy, list, change orders or force a new collection. The OpenAPI file describes each V2 path, parameter and response schema.
| GET path | Purpose / parameters |
|---|---|
/api/v2/status | Versions, age, freshness and independent operations. No parameters. |
/api/v2/market/categories | Discover valid category slugs and coverage. Optional version. |
/api/v2/market/products | Market search/list: 90-day sales metrics, prices, photos, attributes and available trends. |
/api/v2/retail/products | Retail comparisons: 30-day sales metrics, reference-price evidence and calculated spreads. |
/api/v2/products | Versioned alias for the V2 retail list. The unversioned /api/products keeps V1 defaults and full results. |
/api/v2/market/products/{uuid} | Full product and product.history. Optional category, version. |
/api/v2/market/products/{uuid}/history.csv | Daily sales history as CSV. Same parameters as product detail. |
/api/v2/market/overview | Daily sales, categories and movers. Optional version, category. |
/api/v2/retail/overview | Evidence and game coverage under the snapshot’s default policy. Optional version. |
/api/v2/market/search-index/api/v2/retail/search-index | Optional browser optimization. Only version, category, min_sales=0|1 (default 1). Above 20,000 records returns complete:false with no rows. Use the product API for general bot ingestion. |
/api/v2/export/market/api/v2/export/retail | All matching rows, streamed. Product filters and format=json|csv; rejects limit and offset. |
/api/v2/account/status | Authenticated snapshot metadata, client scopes and expiry. No query parameters. |
/api/v2/account/dashboard | All four private datasets, counts and coverage in one bounded snapshot. Accepts only view=redacted|full. Above 10 MiB encrypted source size, returns 413; use the paginated record routes. |
/api/v2/account/orders/api/v2/account/payments/api/v2/account/transfers/api/v2/account/addresses/api/v2/account/activity | Private snapshot records. See authentication and account-specific filters. |
Search, sorting and filters
| Public list parameter | Meaning / default |
|---|---|
q | Optional text or exact lowercase UUID. At most 160 characters and 12 words. |
category | Market slug from categories, or all (default). Retail only accepts all or sealed-tcg. |
min_sales | Nonnegative integer; default 0. Minimum units sold over the dataset’s 90-day market or 30-day retail period. |
sort | Defaults to relevance with a query, otherwise sales volume. Explicit relevance requires a nonempty query. |
direction | asc or desc. Default ascending for name and descending for numeric sorts. Relevance has its own fixed ranking. |
limit / offset | 1–500 rows (default 50); offset 0–1,000,000 (default 0). Use the returned next_offset. |
version | Opaque snapshot ID from status or a previous response. Omit only for the first/current-snapshot request. |
format | json (default) or csv. Set explicitly; Accept: text/csv alone does not select CSV. |
Retail-only parameters
| Parameter | Meaning |
|---|---|
view | all (API default), comparisons, or review. The webpage defaults to comparisons with sales, unlike the API. |
game / package | Exact values such as pokemon and unit. Common package values: unit, case, display, set. |
min_spread | Minimum gross spread in USD. Negative values are allowed. This is before fees, taxes and shipping. |
tiers | Ordered, comma-separated unique tier IDs. Omit to use the snapshot’s default preference order. |
retail_age | Retail-reference age in days, greater than 0 and at most 3650. Omit for the snapshot policy (currently 30). Evaluated at snapshot generation time, not the request time. |
All supported sort keys and price tiers
Market: name, last_sale_usd, average_sale_usd_90d, fair_value_usd, units_sold_90d, volume_usd_90d, price_change_pct_90d, relevance.
Retail: name, baseline_usd, tradepost_last_usd, tradepost_avg_usd, fair_value_usd, gross_spread_usd, markup_pct, gross_margin_pct, units_sold_30d, volume_usd_30d, relevance.
Tier IDs: manufacturer-msrp, walmart-direct, target-direct, manufacturer-direct, other-first-party-retail, distributor-msrp, reported-msrp, reported-retail, derived-package.
Search requires every word, in any order; the final word matches a prefix. Accents and punctuation are normalized. Aliases include ETB → elite trainer box, BB → booster box, BNDL → bundle, PK → pack, MTG → magic the gathering, YUGIOH → yu gi oh, SV → scarlet violet. For example, 151 etb or bundle 151 can match expanded/reordered titles. This differs from V1 substring search. Suggestions are separate; they never silently replace the query.
Unknown, repeated or invalid parameters return 400. Do not send retail filters to market routes. Add an explicit sort to avoid relying on different API/UI defaults; name order and numeric tie-breakers differ from V1.
Read every result, not just the first 50
List JSON has rows, count, returned, limit, offset, next_offset and version. count is the total matching products; returned is this page’s size. Stop only when next_offset is null.
from tradepost_v2 import TradepostV2, require_fresh
import os
api = TradepostV2(os.environ["TRADEPOST_V2_BASE_URL"])
status = api.get("/api/v2/status")
snapshot = status["datasets"]["retail"]
require_fresh(snapshot, max_age_hours=26)
staged = []
for page in api.pages("retail", version=snapshot["version"],
view="comparisons", min_sales=1,
sort="volume_usd_30d", limit=500):
require_fresh(page, max_age_hours=26)
staged.extend(page["rows"])
# Only now replace the bot's previous catalog with staged.
print(snapshot["version"], len(staged))
The helper keeps the first version on every subsequent request and validates that pagination advances. A pruned version returns 409: discard the staged run, reread status and start again. Public responses also include a version-pinned next-page Link header; if following it, restrict requests to your configured origin.
Example market JSON structure (selected fields)
This illustrates shape and source-preserved types, not current prices or a complete response.
{
"version": "20261023T151335Z-0519bd4a60",
"market_snapshot_at": "2026-10-23T15:13:35+00:00",
"count": 2, "returned": 1, "limit": 1,
"offset": 0, "next_offset": 1,
"rows": [{
"tradepost_id": "cde67aae-c53f-42c7-a54e-f947f334e1bb",
"name": "2026 Topps Vault Marvel Studios Hobby Box",
"category": "sealed-wax",
"last_sale_usd": "1804.87",
"fair_value_usd": null,
"units_sold_90d": 17
}]
}Product fields and price meanings
| Fields | How the bot should use them |
|---|---|
tradepost_id, category, name, collection / set, attributes, package_type | Keep the original UUID/title. Confirm category, package, set and variant before matching products. Titles are not unique IDs. |
last_sale_usd / tradepost_last_usd | Last completed sale observed in the dataset; not a live sell offer. |
average_sale_usd_90d / tradepost_avg_usd | Market 90-day / retail 30-day completed-sale averages. Do not compare the periods as though identical. |
fair_value_usd | Tradepost’s separate estimate; missing coverage remains unknown. Check fair_value_snapshot_at where supplied (retail metadata carries it in summary). |
baseline_usd, baseline_tier, baseline_status | Reference selected under the effective price-evidence policy. This can differ from historical retail_msrp. |
baseline_url, baseline_checked_at, baseline_candidates, baseline_rejections | Evidence and eligibility decisions. A new market collection does not make old reference evidence fresh. |
gross_spread_usd, markup_pct, gross_margin_pct | Sale minus selected baseline, and the related percentages. They exclude fees, shipping and tax; missing inputs remain unknown. |
units_sold_90d / units_sold_30d, volume_usd_90d / volume_usd_30d | Observed unit totals and USD sales volume for the stated period. These are not trade counts or stock levels. |
comparison_status, review_reason, baseline_gap_reason, research_next_action | Explain usable comparisons, missing evidence and review needs. Do not treat a missing baseline as a free product. |
image_url, trend, history | Source image; compact daily points [date, average_price, units]; detailed daily observations. No-trade days and missing prices are not filled with invented values. |
Types are source-preserved. Prices can be numeric strings, numbers, null or empty strings. Retail units may also be strings. The Python client parses JSON decimal numbers as Decimal; use decimal_or_none for price arithmetic and keep null/empty as unknown.
from tradepost_v2 import decimal_or_none
reference = decimal_or_none(row.get("baseline_usd"))
last_sale = decimal_or_none(row.get("tradepost_last_usd"))
spread = None if reference is None or last_sale is None else last_sale - reference
Retail list photos and 90-day trends are joined from the current market snapshot; rows identify it with market_version and trend_end_date. Their retail prices and 30-day metrics still belong to the retail version. Pinning a retail version does not pin this visual enrichment. For reproducible history, use market detail with an explicit market version.
Bulk exports and individual history
Use exports for a complete catalog or many matching rows. They accept list filters but reject limit and offset. CSV is usually the simplest full-catalog ingestion format.
from tradepost_v2 import TradepostV2, require_fresh
import os
api = TradepostV2(os.environ["TRADEPOST_V2_BASE_URL"])
snapshot = api.get("/api/v2/status")["datasets"]["retail"]
require_fresh(snapshot)
api.download_csv("retail", "retail-comparisons.csv",
version=snapshot["version"], view="comparisons", min_sales=1)
The helper streams to a temporary file and replaces the destination only after a successful transfer. Stage JSON exports similarly; the whole stream must finish before parsing is complete. In bulk JSON, count describes the full snapshot while returned is the actual filtered export size. Bulk exports omit the extra list-page trend/photo joins.
# Set UUID to a sealed-tcg tradepost_id from market search results.
# Set MARKET_VERSION to datasets.market.version from /api/v2/status.
# For another category, change category below to that product's category.
curl --fail-with-body --get "$TRADEPOST_V2_BASE_URL/api/v2/market/products/$UUID" \
--data-urlencode 'category=sealed-tcg' \
--data-urlencode "version=$MARKET_VERSION"
curl --fail-with-body --get "$TRADEPOST_V2_BASE_URL/api/v2/market/products/$UUID/history.csv" \
--data-urlencode 'category=sealed-tcg' \
--data-urlencode "version=$MARKET_VERSION" \
--output product-history.csv
History CSV columns: date, average_price_usd, units_sold, volume_usd, trade_count. Market exports retain V1’s 11 column names/order; retail retains all 41. Use a CSV parser, not string splitting: names/evidence can contain commas, quotes or line breaks. Cells that look like spreadsheet formulas are escaped.
Full export column order
Market · 11 columns
tradepost_id,name,category,collection,last_sale_usd,average_sale_usd_90d,units_sold_90d,volume_usd_90d,price_change_pct_90d,vaulted_available_units,fair_value_usdRetail · 41 columns
tradepost_id,name,set,game,package_type,baseline_usd,baseline_tier,baseline_status,baseline_source_id,baseline_url,baseline_calculation,baseline_checked_at,retail_msrp,tradepost_last_usd,tradepost_avg_usd,gross_spread_usd,markup_pct,gross_margin_pct,units_sold_30d,volume_usd_30d,msrp_status,retail_msrp_url,msrp_source,msrp_calculation,msrp_checked_at,review_reason,packs_per_box,boxes_per_case,decks_per_display,cards_per_pack,additional_cards_per_pack,cards_per_deck,packs_per_bundle,package_facts_status,package_facts_json,baseline_gap_reason,research_next_action,baseline_preferences_json,selection_as_of,baseline_preference_hash,fair_value_usdFreshness, versions and caching
datasets.market.collected_at, datasets.retail.collected_at and list market_snapshot_at tell you when source data was collected. published_at is when it became available. A successful HTTP response or a recent cache hit does not mean a live price.
- Current status labels: fresh through 14 hours, delayed after 14, stale after 26.
- The review preview checks every 15 minutes and collects a public dataset once its snapshot reaches 12 hours of age, while the preview process is running. Collection time and failures can add delay.
- External retail evidence and private accounts are not refreshed by that preview loop. Check their own timestamps and availability.
- Public responses cache for up to 30 seconds in a browser and 60 seconds in shared caches. ETags include query/version/build and a minute bucket; they can change even without a new snapshot.
If-None-Matchcan return 304 with no body. Reuse the previously cached body. Use dataset version changes to schedule full refreshes.- Legacy responses, status, account data, exports and errors are no-store. Snapshot versions eventually expire; 409 means restart from an available version.
There are no application request-rate quotas for public reads, exports or authenticated reads. Page-size and payload limits remain. Upstream collector pacing is separate, and removing reader quotas does not imply unlimited hosting capacity.
Private account access
Retrieve the account page's records
Use your provisioned account read credential in the Bearer header. With activity:read and pii:read, this returns the full records shown on the account page. Without explicit view=full, the API defaults to redacted records.
# Load TRADEPOST_V2_TOKEN from your secret manager.
curl --fail-with-body --get "__ORIGIN__/api/v2/account/dashboard" \
--header "Authorization: Bearer $TRADEPOST_V2_TOKEN" \
--data-urlencode 'view=full'
The JSON response includes snapshot_version, collected_at, coverage, counts and datasets.orders, datasets.payments, datasets.transfers (shipments), and datasets.addresses. Each dataset is an array of all its records. This route has no pagination or date filters. It reads one consistent snapshot and returns 413 above its 10 MiB encrypted-source bound; use individual paginated routes for larger snapshots. Account responses are private and no-store.
| Data | Where to read it |
|---|---|
| Purchased product | Order assetPayload.configDetails.name; assetPayload.assetDetails.name is the set/collection. key.name describes condition/grade. |
| Order details | Native ID/status, source kind, quantities, execution price, merchandise gross, recorded purchase amount, timestamps and linked transfers. Unknown values remain null. |
| Pay-from reference | Full orders/payments expose paymentSource: status, evidence, recorded payment rail and an available masked method (type, nickname, last four and card brand). Full payments also include externalPaymentId and allowlisted transactionMetadata. |
| Addresses and tracking | Full datasets.addresses and datasets.transfers, with linked order IDs. Requires full-detail access. |
| Account charts and purchase summary | The page calculates these from orders/payments; there is currently no separate account-summary API endpoint. Purchase reconciliation includes shipped purchases and is not current on-hand inventory. Sales cover Tradepost only. |
paymentSource.status is configured, unknown, or ambiguous. The evidence preferred_cbid_payment_token_id records configured intent; actualDebitVerified remains false. Missing historical references remain unknown and are never filled from the account's current default. No full bank account, routing number or processor token is exposed. Funding fields are absent from redacted responses.
Order snapshots combine TPX orders and current order executions. sourceKind distinguishes TPX_ORDER and ORDER_EXECUTION; native IDs and statuses remain intact. Execution unit price, merchandise gross and recorded purchase payments are separate fields. Execution totalAmountCents is null because it has no exact source equivalent. Check authenticated coverage.status as well as freshness: complete coverage includes both fully paginated sources and reconciled execution payment references. Historical snapshots without this verification report unknown coverage.
Existing V1 account access has been imported with the original encrypted snapshot and client credentials. New clients still require provisioning. The upstream Tradepost partner key is a collector credential, not the bot’s read token.
For a new client, an operator must register it, grant activity:read, include its credential in an encrypted V2 account snapshot and configure allowed browser origins where needed. Add pii:read only for full details. The compatibility importer retains the original encrypted key envelopes and stable alias secret. Merely copying a token hash is insufficient.
import os
from tradepost_v2 import TradepostV2, require_fresh
# Load the provisioned token from the bot's secret manager/environment.
# Do not put it in a URL, source code, browser storage or logs.
account = TradepostV2(os.environ["TRADEPOST_V2_BASE_URL"],
token=os.environ["TRADEPOST_V2_TOKEN"])
account_status = account.get("/api/v2/account/status")
require_fresh(account_status)
staged_orders = []
for page in account.account_pages("orders", view="redacted", limit=100):
require_fresh(page)
staged_orders.extend(page["rows"])
# Replace the previous order cache only after this entire loop succeeds.
The client adds the Bearer header only to account requests and refuses redirects. It defaults to redacted reads. Full reads require both view=full and the appropriate scope. Server-side bots without an Origin header need no browser CORS allowlist; browser clients do.
| Account routes | Accepted parameters |
|---|---|
status | None. |
| All record routes | view=redacted|full (default redacted), limit=1..100 (default 20), offset=0..1000000. |
orders, payments, transfers | Also statuses, created_after, created_before. |
orders only | Also order_id, transfer_statuses, updated_after, updated_before. |
addresses, activity | Only the common record parameters; no extra filter parameters. |
Status filters are comma-separated uppercase IDs, at most 30. Date bounds are inclusive and require a timezone, for example 2026-10-01T00:00:00Z. Account pagination is nested under pagination, including total_count, has_next_page and next_offset. Accounts do not accept a version parameter: the helper checks snapshot_version and aborts if it changes between pages.
activity contains orders, payments and transfers, each with its own pagination object. Use the individual routes for complete ingestion. Account data are snapshots, not live order execution; neither full nor redacted mode permits writes.
Errors and retries
Application errors use {"error":"message"}; public errors also include a request ID. HTTP status remains authoritative. A proxy can return HTML instead of JSON, so check status and content type.
| Status | Bot action |
|---|---|
| 200 / 304 | 200: validate the body and source age. 304: reuse the saved body; do not JSON-parse an empty response. |
| 400 | Fix parameters; do not retry unchanged. Common causes: old page keys, duplicate keys, unsupported filters or invalid sort. |
| 401 / 403 | Stop private ingestion. Check credential expiry/revocation, scopes, snapshot inclusion and Origin configuration. Do not repeatedly retry bad credentials. |
| 404 / 405 | Check the route/product and HTTP method. Legacy aliases use the unversioned paths. Reads cannot perform writes. |
| 409 | Discard staged public pages, read status and restart with an available version. The Python helper also raises SnapshotChanged if account pages cross versions. |
| 429 | V2 does not impose an application quota. If infrastructure returns 429, respect Retry-After and reschedule. |
| 500 / 502 / 503 / 504 or network failure | Use bounded retries with backoff, then retain the last complete cache and report the failed refresh. Persistent 503 may mean a dataset or account configuration is absent. |
The example client uses a 30-second request timeout and at most three attempts for network errors and 429/502/503/504. It respects Retry-After; waits above 30 seconds are returned to the bot scheduler rather than retried early. It does not automatically retry 400/401/403/404/405/409 or a generic 500. Choose an overall job deadline in the bot as well.
V1 compatibility reference
These unversioned paths preserve the original contract. They use the same indexed snapshots as V2; they do not proxy requests to the old site.
| Existing request | Preserved behaviour |
|---|---|
/api/products, /api/products.json, /api/products.csv, /retail/report.json, /retail/report.csv | All matching retail rows. Default comparisons with at least one sale. Accepts V1 page/page_size state without truncating the result. Retail Accept negotiation is preserved. |
/api/status | Flat V1 retail status, market version/count and account version when configured. V1 uses its original 36-hour stale threshold. |
/api/market/status, /api/market/categories | V1 market metadata and category structure. |
/api/market/products, .json, .csv | V1 limit/offset pagination, filters, next_offset, Link and bulk_manifest. Default volume descending; maximum 10,000-result window. Use bulk shards for the full universe. |
/api/market/products/{uuid}, /{uuid}/history.csv | Original product detail and daily-history formats. |
/data/manifest.json, /market-data/manifest.json and their versioned shards | Original public manifests and source shard bytes. Only manifest-listed public objects are served. |
/retail/matches.csv, ranked-comparisons.csv, review-queue.csv, sold-comparisons.csv, quality-summary.json | Original static-report data routes, generated from the current snapshot. |
/api/account/{status,orders,payments,transfers,addresses,activity} | Existing Bearer credentials, scopes, redacted IDs and response structure. Full records still require explicit view=full and pii:read. |
Legacy search keeps literal case-insensitive substring matching and natural name ordering. V2 adds token/prefix/alias search. Choosing the versioned API is an explicit integration change; swapping the server behind the existing hostname does not require that change.