Skip to content

API Documentation

Jump to bottom
Vittorio Giovara edited this page Oct 31, 2026 · 21 revisions

BAN Price API

API keys and the gateway at https://api.mtgban.com/ are documented in the site guide's API tab, with an OpenAPI specification for each version. This page covers the same API on the game sites directly, with a sig signature.

This page documents version 2, under /api/v2/. Version 1, under /api/mtgban/, is still served; Porting from v1 to v2 maps every version 1 field and option to its version 2 equivalent.

Data format

Responses are JSON, compressed with GZIP. Every response has a meta section with the date of the request, the API version ("2") and the base_url of the store redirect. A request that fails carries an error string instead of prices.

Prices are keyed by card id, then by finish, then by store tag, and each store lists its prices one per condition, best condition first, so the first entry is the store's best price for that finish.

  • The finish is the one the card is sold in: nonfoil, foil, etched, a game's own such as coldfoil or reverseholofoil, or sealed for a sealed product. The finishes endpoint lists the ones a game uses.
  • Each entry has a price in FLOAT64: the store's best price in that condition, the lowest for retail and the highest offer for buylist. Prices are in USD.
  • condition is NM (Near Mint), SP (Slightly Played), MP (Moderately Played), HP (Heavily Played) or PO (Poor), and absent for an index price (such as TCGLow) and for sealed products. TCGplayer calls SP Lightly Played and PO Damaged; each store's own scale is read into these five.
  • qty (INT) is the copies the store's own listings in that condition hold, or on a buylist the copies the store buys.
  • available (INT) is every copy in that condition on sale at the store at any price, where it is counted.
  • A missing qty or available means the store does not say, never zero; a missing qty on a buylist means no limit.
  • With an id that groups several printings, such as tcg or mkm, a condition holds the best price and the summed quantities of all of them.

A missing store, card or price is left out of the response rather than sent empty.

{
    "meta": {
        "date": "STRING",
        "version": "2",
        "base_url": "STRING"
    },
    "retail": {
        "STRING": {
            "nonfoil": {
                "STRING": [
                    { "condition": "NM", "price": 0.0, "qty": 0 },
                    { "condition": "SP", "price": 0.0, "qty": 0 }
                ],
                "STRING": [
                    { "condition": "NM", "price": 0.0, "available": 0 }
                ],
                "STRING": [
                    { "price": 0.0 }
                ]
            },
            "foil": {
                "STRING": [
                    { "condition": "NM", "price": 0.0, "qty": 0 }
                ]
            }
        }
    },
    "buylist": {}
}

Options

Output id

Cards are keyed by their MTGBAN id unless the id query parameter asks for another one:

id value description
ban MTGBAN ids (the default)
tcg TCGplayer product ids
scryfall Scryfall ids
mtgjson MTGJSON UUIDs
mkm Cardmarket ids
ck Card Kingdom ids
name Card names

ban and ck give each finish its own id, so a card's foil prices sit under a second id (<id>_f for MTGBAN ids). tcg, mkm and name can cover several printings with one id; their prices are then the best of all of them, with the quantities summed. With mkm, a card is keyed by the product Cardmarket prices it under, and by our card database's Cardmarket id only where Cardmarket does not price it, so it covers every game Cardmarket sells. Any other id value is an error.

Stores

Set vendor to one store tag, or several separated by commas, to get only those stores' prices. Only stores your signature can read are returned.

Finish

Set finish to one finish key, such as foil, to get only that finish's prices. It does not apply to sealed products.

Endpoints

The examples use https://mtgban.com, the Magic site; every game site serves the same endpoints for its own game.

Edition snapshot

Prices for a single edition. Set codes follow Scryfall's, and the sets endpoint lists the ones a game supports. Request retail, buylist, or all for both.

Sealed products

The same for sealed products, with retail and buylist prices in a single call.

Single card

Prices for one card, every finish included. The card can be named by its MTGBAN id, MTGJSON UUID, Scryfall id or TCGplayer product id.

Search

Prices for the cards a search finds, with the same query syntax as the site's search. URL-encode the query, / included.

Cards are keyed by Scryfall id, and sealed products by MTGJSON UUID, unless id asks for another. A store, condition or price filter in the query narrows the prices returned as well as the cards.

The sets endpoint

[
  "10E",
  "2ED",
  "2X2"
]

Every set code with prices, to use in an edition snapshot. filter=sealed or filter=singles keeps only the sets with sealed products or with singles.

The stores endpoint

{
  "sellers": [
    { "shorthand": "CT", "name": "Card Trader", "country": "EU", "quantities": true, "updated": "STRING" },
    { "shorthand": "TCGLow", "name": "TCG Low", "index": true, "updated": "STRING" }
  ],
  "vendors": [
    { "shorthand": "CK", "name": "Card Kingdom", "quantities": true, "credit_multiplier": 1.3, "updated": "STRING" }
  ]
}
  • shorthand is the store's tag in price lists, and name its display name.
  • index marks a store whose prices index a market, which carry no condition; quantities a store whose prices carry qty.
  • credit_multiplier is what a vendor's store credit is worth against its cash price, 1.3 for 30% more; updated is when the store's prices were collected.
  • Only the stores you can read are listed. filter=sealed or filter=singles keeps only the stores with sealed or singles prices.

The finishes endpoint

[
  { "value": "nonfoil", "label": "Non-foil", "count": 0 },
  { "value": "foil", "label": "Foil", "count": 0 },
  { "value": "sealed", "label": "Sealed", "count": 0 }
]

The finish keys the game's prices use, commonest first. count is how many cards carry the finish, or products for sealed, and filter keeps singles or sealed.

Full snapshot (deprecated)

Every price your signature can read, for retail, buylist, or all:

Full snapshots are large, need a signature and only come as JSON. This endpoint is deprecated and should not be used; request editions or cards instead.

Redirect

MTGBAN offers a free redirect to any store's page for a card: concatenate the response's meta.base_url, the store tag and the card id, which can be an MTGBAN id, MTGJSON UUID, Scryfall id or TCGplayer product id.

https://mtgban.com/go/CK/7da23b15-dfb8-4267-9b33-d7a4c035c434

CSV output

Replace .json with .csv to get a CSV instead, for every endpoint but all and the full snapshots. The price CSV is the same as version 1's, one row per card and finish, and takes tag=names to name stores in full. It is meant to be read by people rather than parsed, and leaves out what a table cannot show.

Authentication

Requests carry the sig query parameter, which grants the stores and modes (retail, buylist, sealed) your access level includes. Without one, edition, sealed and single card requests answer with a few demo stores, a search answers with no prices, and full snapshots are refused.

Response codes

code description action
200 Success JSON or CSV is returned
301 Moved permanently Request was made over an insecure channel, use https
429 Too many requests Perform fewer requests at the same time
502 Bad gateway Server starting, try again later
503 Service unavailable Server loading, try again later

A 200 response can still carry an error field; check it before reading prices.

Rate limits

Each user is granted a maximum of 10 requests per second.

Changelog

2026-10-07

  • Version 2 search under /api/v2/search/

2026-10-06

  • Version 2 under /api/v2/: prices by finish and by condition, with qty and available
  • Version 2's stores.json describes each store, and finishes.json lists the finishes prices are keyed by
  • Version 2 takes no tag: prices are keyed by store tag

2025-08-25

  • Added option to retrieve store names
  • Removed compatibility layer for store names, now tags are provided by default

2024-09-03

  • You can set store name display style with tag query parameter.
  • Sealed and Index scrapers do not initialize the condition field to a constant "NM"

2024-07-04

  • New endpoint to retrieve available store keys

2024-05-01

  • The quantities dictionary is available
  • The generic cond field is available
  • Per-condition pricing requirements are relaxed
  • New endpoint to retrieve available set codes

2024-04-10

  • The API supports reporting sealed prices

2022-08-10

  • Quantity and conditions query parameters are decoupled and can be requested at the same time.
  • The condition dictionary for buylist data returns a full map, containing the

2021-10-04

  • It is possible to export data as csv.

2021-08-17

  • You can obtain condition prices from single card requests too.

2021-07-07

  • You can request data from a single vendor. The output will include per condition prices as available

2021-07-01

  • You can use TCG IDs in singles input requests
  • You can request quantities available by setting qty=true query parameter (only available for selected vendors)
  • You can go to the vendor retail page by concatenating the Metadata.BaseURL, the vendor tag, and the id/hash of the card

2021-06-01

  • Initial public version

Clone this wiki locally