DEVELOPERS / API & bot guideVersion 2 · Verified October 23, 2026
Built for integration

Tradepost API.
Developer documentation.

Read product prices, sales history, retail evidence and authorized account snapshots. This guide covers the original compatible API and the optional V2 endpoints.

GET / HEADJSON & CSVNo application request quotasPublic data needs no key

One host, two API contracts

Existing clients use /api/… . New integrations use /api/v2/… .

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 settingHow it works
Existing production hostnamehttps://tradepost.bidzone.com. Clients keep this hostname. Check /api/v2/deployment for the active implementation; V1 continues serving until V2 snapshots are ready.
This hosthttps://YOUR-HOST. A trycloudflare.com address is a temporary review host, not permanent bot hosting.
Existing requestsUse the original /api/products, /api/market/… and /api/account/… paths. Legacy aliases and bulk manifests remain available.
New requestsUse the /api/v2/… reference below. Both contracts read the same stored snapshots.
Public accessNo password or API key is required.
Private accessUse 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

  1. Check status. Read /api/v2/status and select datasets.market or datasets.retail. Check its collection time and the relevant collection operation.
  2. 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.
  3. 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.
  4. Validate. Check the final page/export completed, confirm source age, and handle absent prices explicitly. Match exact product IDs plus category/package/edition details.
  5. 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 pathPurpose / parameters
/api/v2/statusVersions, age, freshness and independent operations. No parameters.
/api/v2/market/categoriesDiscover valid category slugs and coverage. Optional version.
/api/v2/market/productsMarket search/list: 90-day sales metrics, prices, photos, attributes and available trends.
/api/v2/retail/productsRetail comparisons: 30-day sales metrics, reference-price evidence and calculated spreads.
/api/v2/productsVersioned 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.csvDaily sales history as CSV. Same parameters as product detail.
/api/v2/market/overviewDaily sales, categories and movers. Optional version, category.
/api/v2/retail/overviewEvidence 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/statusAuthenticated snapshot metadata, client scopes and expiry. No query parameters.
/api/v2/account/dashboardAll 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 parameterMeaning / default
qOptional text or exact lowercase UUID. At most 160 characters and 12 words.
categoryMarket slug from categories, or all (default). Retail only accepts all or sealed-tcg.
min_salesNonnegative integer; default 0. Minimum units sold over the dataset’s 90-day market or 30-day retail period.
sortDefaults to relevance with a query, otherwise sales volume. Explicit relevance requires a nonempty query.
directionasc or desc. Default ascending for name and descending for numeric sorts. Relevance has its own fixed ranking.
limit / offset1–500 rows (default 50); offset 0–1,000,000 (default 0). Use the returned next_offset.
versionOpaque snapshot ID from status or a previous response. Omit only for the first/current-snapshot request.
formatjson (default) or csv. Set explicitly; Accept: text/csv alone does not select CSV.

Retail-only parameters

ParameterMeaning
viewall (API default), comparisons, or review. The webpage defaults to comparisons with sales, unlike the API.
game / packageExact values such as pokemon and unit. Common package values: unit, case, display, set.
min_spreadMinimum gross spread in USD. Negative values are allowed. This is before fees, taxes and shipping.
tiersOrdered, comma-separated unique tier IDs. Omit to use the snapshot’s default preference order.
retail_ageRetail-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

FieldsHow the bot should use them
tradepost_id, category, name, collection / set, attributes, package_typeKeep the original UUID/title. Confirm category, package, set and variant before matching products. Titles are not unique IDs.
last_sale_usd / tradepost_last_usdLast completed sale observed in the dataset; not a live sell offer.
average_sale_usd_90d / tradepost_avg_usdMarket 90-day / retail 30-day completed-sale averages. Do not compare the periods as though identical.
fair_value_usdTradepost’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_statusReference selected under the effective price-evidence policy. This can differ from historical retail_msrp.
baseline_url, baseline_checked_at, baseline_candidates, baseline_rejectionsEvidence and eligibility decisions. A new market collection does not make old reference evidence fresh.
gross_spread_usd, markup_pct, gross_margin_pctSale 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_30dObserved 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_actionExplain usable comparisons, missing evidence and review needs. Do not treat a missing baseline as a free product.
image_url, trend, historySource 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_usd

Retail · 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_usd

Freshness, 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-Match can 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.

DataWhere to read it
Purchased productOrder assetPayload.configDetails.name; assetPayload.assetDetails.name is the set/collection. key.name describes condition/grade.
Order detailsNative ID/status, source kind, quantities, execution price, merchandise gross, recorded purchase amount, timestamps and linked transfers. Unknown values remain null.
Pay-from referenceFull 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 trackingFull datasets.addresses and datasets.transfers, with linked order IDs. Requires full-detail access.
Account charts and purchase summaryThe 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 credentials are preserved; new clients require provisioning.

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 routesAccepted parameters
statusNone.
All record routesview=redacted|full (default redacted), limit=1..100 (default 20), offset=0..1000000.
orders, payments, transfersAlso statuses, created_after, created_before.
orders onlyAlso order_id, transfer_statuses, updated_after, updated_before.
addresses, activityOnly 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.

StatusBot action
200 / 304200: validate the body and source age. 304: reuse the saved body; do not JSON-parse an empty response.
400Fix parameters; do not retry unchanged. Common causes: old page keys, duplicate keys, unsupported filters or invalid sort.
401 / 403Stop private ingestion. Check credential expiry/revocation, scopes, snapshot inclusion and Origin configuration. Do not repeatedly retry bad credentials.
404 / 405Check the route/product and HTTP method. Legacy aliases use the unversioned paths. Reads cannot perform writes.
409Discard staged public pages, read status and restart with an available version. The Python helper also raises SnapshotChanged if account pages cross versions.
429V2 does not impose an application quota. If infrastructure returns 429, respect Retry-After and reschedule.
500 / 502 / 503 / 504 or network failureUse 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 requestPreserved behaviour
/api/products, /api/products.json, /api/products.csv, /retail/report.json, /retail/report.csvAll 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/statusFlat V1 retail status, market version/count and account version when configured. V1 uses its original 36-hour stale threshold.
/api/market/status, /api/market/categoriesV1 market metadata and category structure.
/api/market/products, .json, .csvV1 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.csvOriginal product detail and daily-history formats.
/data/manifest.json, /market-data/manifest.json and their versioned shardsOriginal 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.jsonOriginal 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.