API Documentation


This API is open to the app developers to access a centralized inventory system. It's released because the hardest thing to do is keep up with your magic inventory. If every app adopted it, you could manage your inventory from anywhere. I'm sure then we still wouldn't stay on top of it ;)

The second reason this is opened up is to gain access to list generation for importing and exporting your lists to sites like MagicTraders.com and PucaTrade.com. I love the market, and I love trading, that is why Echo exists.

The inventory is controlled by the Multiverse ID, which makes it universal for all apps to work with. Since Judge Foils and other promo cards do not have multiverseids, their multiverseid's start at 100000000. Access the ID reference here. If you have any suggestions here, please email me teeg at echomtg dot com.

PHP Wrapper by Andrew Gioia: https://github.com/andrewgioia/EchoPHP

JAVA Wrapper for Android https://github.com/ardeay/EchoMTG-Java-API-Wrapper/

Have fun ;)
—Teeg

Prerequisites


1. Register a user with EchoMTG so that it can submit API requests.

2. Familiarize yourself with the core concepts of the JSON (JavaScript Object Notation) data format. For more information, see json.org.


LGS Private Store API


Have a store and want to use Echo to track your inventory or spot check prices? We have a special API and pricing package for you, contact us for more details

- User Authentication ^ top

The majority of calls requires user authentication. Soon you will be able to create a user on the fly here as well. This will let you use EchoMTG's preexisting user base without creating your own.

  1. Auth: Retrieving a User tokenPOST


    The user must be auth'd to execute any API call. Make this call by sending the user's Email Address (user) and Password. You will want to store the token to your application's memory or database for further use. A new token is generated every time a user is auth'd from anywhere. To have permanent tokens for users in your application contact teeg at echomtg dot com.

    /api/user/auth/ returns a status, message, token (only if successful) parameter in JSON.

    Example POST for authorizing a user

    Post params:
    email
    password

    Example POST using CURL for authorizing a user

    Post params:
    email
    password

  2. User: Change CurrencyPUT


    The user must be Auth'd to make this call. The call will change the currency shown to a user for all API requests and www.echomtg.com interface price displays. It is called by sending the Currency Code (currency_code) of the card you want to add and the user Token (auth).

    /api/user/change_currency/ returns a status and message parameter in JSON.

    Example POST Curl for changing currency

    Currencies Available

    • USD - U.S. Dollars
    • GBP - British Pounds
    • EUR - Euros
    • AUD - Australian Dollars
    • BRL - Brazilian Real
    • CAD - Canadian Dollars
    • CZK - Czech koruny
    • DKK - Danish Kroner
    • HKD - Hong Kong Dollars
    • HUF - Hungarian Forints
    • ILS - Israeli Shekels
    • JPY - Japanese Yen
    • MYR - Malaysian Ringgits
    • MXN - Mexican Pesos
    • NZD - New Zealand Dollars
    • NOK - Norwegian Kroner
    • PHP - Philippine Pesos
    • PLN - Polish zloty
    • SGD - Singapore Dollars
    • SEK - Swedish Kronor
    • CHF - Swiss Francs
    • TWD - Taiwan New Dollars
    • THB - Thai Baht
    • TRY - Turkish Liras

- Inventory ^ top

The most valuable part of EchoMTG is the inventory (collection) aspect. Being able to manipulate this from multiple applications allows magic players to keep on top of their collections. This is a quick and easy way to add more value to your magic applications for users.

  1. Inventory: Adding CardsPOST


    The user must be Auth'd to make this call. The call will add a card to the user inventory. It is called by sending the Multiverse ID (mid) OR EchoID (emid) of the card you want to add and the user Token (auth).

    Example JSON Post

    Raw Post Body (send your token in a header "Authorization: Bearer XXXXXXXXXXXXXXX")

    { "emid": 92175, "quantity" : 1, "language": "EN", "acquired_price": "4.00", "acquired_date": "5-1-2020", "condition": "MP", "foil": 1 }

    Example Return Value

    /api/inventory/add/ returns a status string, message string, and card object in JSON.

    { status: "success", message: "1 Castle added to inventory.", card: { id: "269", multiverseid: "240", expansion: "Limited Edition Alpha", card_name: "Castle", rarity: "Uncommon", mana_cost: "{{3}}{{w}}", cmc: "4", p_t: null, types: "Enchantment", main_type: "Enchantment", sub_type: "", rating: "2.870", votes: "23", card_text: "

    Untapped creatures you control get +0/+2.

    ", attributes: null, flavor_text: null, power: null, toughness: null, artist: "Dameon Willich", all_sets: "Limited Edition Alpha, Limited Edition Beta, Unlimited Edition, Revised Edition, Fourth Edition, Fifth Edition, Classic Sixth Edition, Seventh Edition", community_rating: "Rating: 2.870 / 5  (23 votes)", type: "Enchantment", main_colors: "White", abilities_colors: "", crawlurl: "http://gatherer.wizards.com/Pages/Card/Details.aspx?multiverseid=240", set_number: null, watermark: null, loyalty: null, other_sets: null, set_code: null, card_number: null, has_image: "1", flip: "0", card_id: "269", last_updated: "2016-04-26 09:20:39", tcg_low: "5.69", tcg_mid: "8.99", change: "6.00", tcg_high: "12.00", foil_price: null, foil_change: "0.00", purchase_link_tcg: "http://store.tcgplayer.com/magic/alpha-edition/castle?partner=ECHOMAGE" } }

    Deprecated GET examples

    Example Get URL for adding a single card

    Example Get URL for adding a single card using EchoID

    Example for adding a single foil card

    Example for adding a single card with a custom acquired value

    Example for adding a single card with a custom acquired date

    Example for adding a single card with a custom condition

    Example for adding multiple of one card

  2. Inventory: Removing CardsPOST


    The user must be Auth'd to make this call. The call will remove a single card from a user's inventory. It is called by sending the Inventory ID (inventory_id) of the card you want to remove and the user Token (auth).

    /api/inventory/remove/ returns a status and message parameter in JSON.

    Example Get URL for remove a single card

  3. Inventory: Adjusting Card ConditionPOST


    The user must be Auth'd to make this call. The call will adjust the price a single card from a user's inventory. It is called by sending the Inventory ID (id) of the card you want to update, the Card Condition (value), and the user Token (auth).

    /api/inventory/change_condition/ returns a status and message parameter in JSON.

    Example Get URL changing a card condition

    Conditions

    • NM  = Near Mint
    • LP  = Lightly Played
    • MP  = Moderately Played
    • HP  = Heavily Played
    • D   = Damaged
    • ALT = Altered
    • ART = Artist Proof
    • PRE = Pre-release
    • TS = Timestamped
    • SGN = Signed
    • B10 = BGS 10
    • B95 = BGS 9.5
    • B9  = BGS 9.0
    • B85 = BGS 8.5
    • B8  = BGS 8.0
    • B75 = BGS 7.5
    • B7  = BGS 7.0
    • P10 = PSA 10
    • P95 = PSA 9.5
    • P9  = PSA 9.0
    • P85 = PSA 8.5
    • P8  = PSA 8.0
    • P75 = PSA 7.5
    • P7  = PSA 7.0
  4. Inventory: Adjusting Card LanguagePOST


    The user must be Auth'd to make this call. The call will adjust the price a single card from a user's inventory. It is called by sending the Inventory ID (id) of the card you want to update, the Card Language (value), and the user Token (auth).

    /api/inventory/change_condition/ returns a status and message parameter in JSON.

    Example Get URL for changing a cards language

    Languages

    • EN  = English (default)
    • FR  = French
    • DE  = German
    • RU  = Russian
    • IT  = Italian
    • ES  = Spanish
    • PT  = Portuguese
    • CT  = Chinese Traditional
    • CS  = Chinese Simplified
    • JP  = Japanese
    • KP  = Korean
  5. Inventory: Adjusting Acquired PricePUT


    The user must be Auth'd to make this call. The call will adjust the price a single card from a user's inventory. It is called by sending the Inventory ID (id) of the card you want to update, the price Adjusted Price (adjusted_price) the user Token (auth).

    /api/inventory/adjust/ returns a status and message parameter in JSON.

    Example Get URL for remove a single card

  6. Inventory: Toggle FoilPOST


    The user must be Auth'd to make this call. The call will toggle the card in the user's inventory list to be foil or not foil. It is called by sending the Inventory ID (inventory_id) and the foil value (1=foil 0=not-foil) of the card you want to modify and the user Token (auth). This will automatically change the current value of the card. To reflect that change you will need to reload your data.

    /api/inventory/toggle_foil/ returns a status and message parameter in JSON.

    Example Get URL for toggling the foil status of an inventory record

  7. Inventory: Toggle TradablePOST


    The user must be Auth'd to make this call. The call will toggle the card in the user's inventory item to be tradable or not tradable. It is called by sending the Inventory ID (inventory_id) and the (tradable) value (1=true 0=false) of the item you want to modify and the user Token (auth).

    /api/inventory/toggle_tradable/ returns a status and message parameter in JSON.

    Example Get URL for toggling the foil status of an inventory record

  8. Inventory: Adjust Acquired DatePUT


    The user must be Auth'd to make this call. The call will modify the acquired value of a card on the user's inventory list. It is called by sending the Inventory ID (id) and new date value in the format dd-mm-yyyy (value) of the card you want to modify and the user Token (auth).

    /api/inventory/adjust_date/ returns a status and message parameter in JSON.

    Example Get URL for adjusting the sold date of an inventory record


  9. The user must be Auth'd to make this call. The call will search the user's inventory. It is called by sending a name, expansion, setCode, multiverseID, AND/OR emid (Echo ID) of the card you want to search for AND the user Token (auth).

    /api/inventory/search/ returns a status string, message string, and results object in JSON.

    { message: "Search successfully executed in 0.0155 seconds", currency: "USD", results: [ { inventoryID: "24955120", echoID: "107622", multiverseID: "447211", name: "Snapping Drake", expansion: "Core Set 2019", setCode: "M19", acquiredPrice: "0.14", condition: "NM", lang: "EN", noteID: "0", acquiredOn: "2018-11-19 12:03:39", enteredOn: "2019-01-12 17:46:53", updatedOn: "2019-01-12 17:48:44" } ], status: "success" }

    Example search by card name

    Example search by echo id

    Example search by expansion

    Example search by expansion and name

    Example search by set code

  10. Inventory: ViewGET


    The user must be Auth'd to make this call. The call will return a filter list of the user's inventory. It is called by sending the start (number which we start return cards) and limit (amount of cards returned), and the user Token (auth). Other options are available like color and type.

    /api/inventory/view/ returns a status, meta object, items array, and message parameter in JSON.

    Example Get URL for viewing inventory

    Example Get URL for viewing inventory by price descending. All sort options: price, cmc, foil_price, date_aquired, and set.

    Example Get URL for viewing inventory using a search filter. Search is by card name.

    Example Get URL for viewing inventory by color Colors are: Colorless, Multicolor, Blue, Red, White, Black, Green, and Land.

    Example Get URL for viewing inventory by type Types are: Planeswalker, Sorcery, Instant, Creature, Artifact, Legendary, Green, and Land.

    Example Get URL with only accessing a specific set using set codes.

    Example Get URL with multiple options

  11. Inventory: DumpGET


    The user must be Auth'd to make this call. The call returns high level statistics for a users inventory. This call is used to sync inventory in personal project or public iOS or Android apps. This endpoint is called by sending the user Token (auth). It returns JSON.

    /api/inventory/dump/ returns a status, headerMap object array that links up the short keys to name, and inventoryData which is an array or inventory data.

    For large inventories, this API call may take some time.

    Example Get URL for dumping all inventory

    Example Get URL for dumping all inventory and deleted inventory

    Example Get URL for dumping all inventory and deleted inventory form a specific date (this is used for syncing)

  12. Inventory: StatsGET


    The user must be Auth'd to make this call. The call returns high level statistics for a users inventory. It is called by sending the user Token (auth).

    /api/inventory/stats/ returns a status, stats array, and message parameter in JSON.

    Example Get URL for viewing inventory

  13. Inventory: Card Reference GET


    The user must be Auth'd to make this call. This call returns all the cards in the echomtg database, their multiverse id, echo id, name, expansion, and set code.

    https://www.echomtg.com/api/data/card_reference/ returns a status, cards array, and message parameter in JSON. Note you can specify to return this information in CSV format.

    Example Get URL for retrieving a card reference in JSON.

    Example Get URL for retrieving a card reference in CSV format.

    Example Get URL for retrieving a card reference of just promos in JSON.

    Example Get URL for retrieving a card reference of just promos in CSV format.

  14. Inventory: Set Reference GET


    The user must be Auth'd to make this call. This call returns all the sets or expansions in the echomtg database, their set_code, and name.

    https://www.echomtg.com/api/data/set_reference/ returns a status, sets array, and message parameter in JSON. Note you can specify to return this information in CSV format.

    Example Get URL for retrieving a set reference in JSON.

    Example Get URL for retrieving a set reference in CSV format.

- Earnings ^ top

Earnings is an area that holds records of card sales. This information is used for tracking the user's selling statistics. Records track the date the sale occurred, the sale price, the price you acquired the card for, and whether it is foil or not. This system let's you accurately track the loss and gain from a user's card sales. All methods to control this portion of the user account are accessible through the EchoAPI. Earning is currently only offer to paying accounts.

  1. Earnings: Add Record to SoldPOST


    The user must be Auth'd to make this call. The call will add a card to the user's sold list. It is called by sending the Multiverse ID (mid) of the card you want to add and the user Token (auth).

    /api/earnings/add/ returns a status and message parameter in JSON.

    Example Get URL for adding a single card

    Example for adding a single foil card

    Example for adding a single card with a custom acquired value

    Example for adding multiple of one card

  2. Earnings: Adjust Record Sale/Trade ValuePUT


    The user must be Auth'd to make this call. The call will modify the sale/trade value of a card on the user's sold list. It is called by sending the Earnings ID (id) and new float value (value) of the card you want to modify and the user Token (auth).

    /api/earnings/adjust_sold/ returns a status and message parameter in JSON.

    Example Get URL for adjusting the price of an earnings record

  3. Earnings: Adjust Record Acquired ValuePUT


    The user must be Auth'd to make this call. The call will modify the acquired value of a card on the user's sold list. It is called by sending the Earnings ID (id) and new float value (value) of the card you want to modify and the user Token (auth).

    /api/earnings/adjust_acquired/ returns a status and message parameter in JSON.

    Example Get URL for adjusting the price of an earnings record

  4. Earnings: Adjust Record Sold DatePUT


    The user must be Auth'd to make this call. The call will modify the acquired value of a card on the user's sold list. It is called by sending the Earnings ID (id) and new date value in the format dd-mm-yyyy (value) of the card you want to modify and the user Token (auth).

    /api/earnings/adjust_date/ returns a status and message parameter in JSON.

    Example Get URL for adjusting the sold date of an earnings record

  5. Earnings: Remove RecordPOST


    The user must be Auth'd to make this call. This call permanently removes an earnings record.

    /api/earnings/remove/ returns a status and message parameter in JSON.

    Example Get URL for removing an earnings record

- Notes ^ top

Notes are plain text records associated to inventory items. All notes endpoints are accessible through the EchoAPI at all levels.

  1. Notes: NoteGET


    Access a note by sending the Note ID (id) and the user Token (auth).

    /api/notes/note/ returns a status and note object in JSON.

    Example Get URL for accessing a note

  2. Notes: CreatePOST


    The call will add a note to an inventory item. It is called by sending the Inventory ID (inventory_id) and a note value (note) which is plain text and the user Token (auth).

    /api/notes/create/ returns a status, note_id, and message parameter in JSON.

    Example Post URL for adding a note

  3. Notes: EditPOST


    The call will modify the plain text on a note. It is called by sending the Note ID (note_id), new note text (note) and the user Token (auth).

    /api/notes/edit/ returns a status and message parameter in JSON.

    Example POST for updating a note.

  4. Notes: DeletePOST


    This call delete a note. It is called by sending the Note ID (note_id) and the user Token (auth).

    /api/notes/delete/ returns a status and message parameter in JSON.

    Example POST for deleting a note

- Lists ^ top

Lists let players group inventory records. This is useful for tracking the running values of collection pieces and their locations e.g. Decks, Cubes, Lent items, and player pools. In order to add a card to a list, it must be in the users inventory.

  1. Lists: Create ListPOST


    The user must be Auth'd to make this call. A list is create for the user that is Auth'd. If the user level does not allow a new list to be made, and error will be thrown in the message.

    /api/lists/create/ returns a status, list object, and message parameter in JSON.

    Example Get URL for creating a list

  2. Lists: Edit ListPUT


    The user must be Auth'd to make this call. This call let's a user modify the name and description of a pre-existing list.

    /api/lists/edit/ returns a status, list object, and message parameter in JSON.

    Example Get URL for creating a list

  3. Lists: Make List Public ListPUT


    The user must be Auth'd to make this call. This call will make a public url for the list for sharing and make it viewable on search engines.

    /api/lists/make_public/ returns a status and message parameter in JSON.

    Example Get URL for re-activating a list

  4. Lists: Deactivate ListPUT


    The user must be Auth'd to make this call. This call will deactivate (Echo's equivalent of remove) the specified list.

    /api/lists/toggle_status/ returns a status and message parameter in JSON.

    Example Get URL for deactivating a list

  5. Lists: Activate ListPUT


    The user must be Auth'd to make this call. This call will re-activate the specified list.

    /api/lists/toggle_status/ returns a status and message parameter in JSON.

    Example Get URL for re-activating a list

  6. Lists: Get all ListsGET


    The user must be Auth'd to make this call. This call will return all of the user's activated lists. Optional order modifier takes in last_edited (default), created, alpha_desc, and alpha_asc.

    /api/lists/all/ returns a status, array of lists, and message parameter in JSON.

    Example Get URL for getting a list of lists

    Example Get URL for getting a list of lists alphabetically

  7. Lists: Get ListGET


    The user must be Auth'd to make this call. This call will return an array of card objects of the specified list. You retrieve the list id from call /api/lists/all/ for a list of lists with ids in details.

    /api/lists/get/ returns a status, array of lists, and message parameter in JSON.

    Example Get URL for getting a list

    Example Get URL for getting a list with a pre-formatted html view

  8. Lists: Add Card to ListPOST


    The user must be Auth'd to make this call. This call will add a card to the specified list.

    /api/lists/add/ returns a status and message parameter in JSON.

    Example Get URL for adding a card to list

    Example Get URL for adding a card to list in sideboard

  9. Lists: Toggle FoilPUT


    The user must be Auth'd to make this call. The call will toggle the card in the user's list to be foil or not foil. It is called by sending the List Item ID (id), List ID (list_id) and the foil value (1=foil 0=not-foil) of the card you want to modify and the user Token (auth). This will automatically change the current value of the card. To reflect that change you will need to reload your data.

    /api/lists/toggle_foil/ returns a status and message parameter in JSON.

    Example Get URL for toggling the foil status of an list item record

  10. Lists: Toggle SideboardPUT


    The user must be Auth'd to make this call. This call will toggle the card in the user's list to be in the side board or not to be in the sideboard. It is called by sending the List Item ID (id), List ID (list_id) and the (sb) value (1 for side board, 0 for main deck) of the card you want to modify and the user Token (auth). This will automatically change the current value of the card. To reflect that change you will need to reload your data.

    /api/lists/toggle_sideboard/ returns a status and message parameter in JSON.

    Example Get URL for toggling the foil status of an list item record

  11. Lists: Remove a Card from ListPOST


    The user must be Auth'd to make this call. This call will add a card to the specified list.

    /api/lists/remove/ returns a status and message parameter in JSON. list is the list id, id if the list item id.

    Example Get URL for removing a card to from list

- Watch Lists ^ top

Watch list is an area that holds lists of cards to track movement. Everyday Echo procesess each watch list to detect if movement is beyond the threshold the user set (20% 100%+), if it is, they receive an email or text message. Watch lists are currently only offered to paying accounts.

  1. WatchLists: Add Record to WatchlistPOST


    The user must be Auth'd to make this call. The call will add a card to the user's watch list. It is called by sending the Multiverse ID (mid) of the card you want to add and the user Token (auth).

    /api/watchlist/add/ returns a status and message parameter in JSON.

    Example Get URL for adding a single card

    Example for adding a single foil card

  2. WatchLists: Adjust ThresholdPUT


    The user must be Auth'd to make this call. This call changes the percentage of change threshold (-10, -4, 5, 20, etc) required to notify the user.

    /api/watchlist/threshold/ returns a status and message parameter in JSON.

    Example Get URL for changing the the threshold of record

  3. WatchLists: Adjust Message TypePUT


    The user must be Auth'd to make this call. This call changes the medium which notifications (value) are received (0 = off, 1 = email, 2 = SMS message, 3 = email+SMS).

    /api/watchlist/notification/ returns a status and message parameter in JSON.

    Example Get URL for changing the the notification of record

  4. WatchLists: Remove RecordPOST


    The user must be Auth'd to make this call. This call permanently removes an earnings record.

    /api/watchlist/remove/ returns a status and message parameter in JSON.

    Example Get URL for removing an watch list record

  5. Watchlist: ViewGET


    The user must be Auth'd to make this call. The call will return a filter list of the user's watchlist. It is called by sending the start (number which we start return cards) and limit (amount of cards returned), and the user Token (auth). Other options are available like color and type.

    /api/watchlist/view/ returns a status, meta object, items array, and message parameter in JSON.

    Example Get URL for viewing inventory

    Example Get URL for viewing inventory by price descending. All sort options: price, cmc, foil_price, date_aquired, and set.

    Example Get URL for viewing inventory using a search filter. Search is by card name.

    Example Get URL for viewing inventory by color Colors are: Colorless, Multicolor, Blue, Red, White, Black, Green, and Land.

    Example Get URL for viewing inventory by type Types are: Planeswalker, Sorcery, Instant, Creature, Artifact, Legendary, Green, and Land.

    Example Get URL with only accessing a specific set using set codes.

    Example Get URL with multiple options

- Buy Lists ^ top

Buy list is an area that holds a list of cards grouping into buy profiles. Buy lists are used by both players and stores, and can be managed privately, but shared publicly. Buy Lists are currently only offered to mythic level accounts.

  1. BuyLists: Add Record to buy listPOST


    The user must be Auth'd to make this call. The call will add a card to the user's buy list. It is called by sending the Multiverse ID (mid) of the card you want to add along with the buy list profile id (profile), and the user Token (auth).

    /api/buylist/add/ returns a status and message parameter in JSON.

    Example Get URL for adding a single card

    Example for adding a single foil card

  2. https://www.echomtg.com/api/buylist/expiry/id=240&value=05-06-2016auth=XXXXXXXXXXXXXXX

  3. BuyLists: Remove RecordPOST


    The user must be Auth'd to make this call. This call permanently removes a buylist record.

    /api/buylist/remove/ returns a status and message parameter in JSON.

    Example Get URL for removing an watch list record

  4. BuyLists: Create ProfilePOST


    Each card on the buy list must be assign to a profile. Profiles have a percentage (for amount taken off tcg_low), name, and description. Profile have other options like show or hide prices. The user must be Auth'd to make this call.

    /api/buylist/create_profile/ returns a status and message parameter in JSON.

    Example Get URL adding a buylist profile.

  5. Buylist: ViewGET


    The user must be Auth'd to make this call. The call will return a filter list of the user's buy list. It is called by sending the start (number which we start return cards) and limit (amount of cards returned), and the user Token (auth). Other options are available like color and type.

    /api/buylist/view/ returns a status, meta object, items array, and message parameter in JSON.

    Example Get URL for viewing inventory

    Example Get URL for viewing inventory by price descending. All sort options: price, cmc, foil_price, date_acquired, and set.

    Example Get URL for viewing inventory using a search filter. Search is by card name.

    Example Get URL for viewing inventory by color Colors are: Colorless, Multicolor, Blue, Red, White, Black, Green, and Land.

    Example Get URL for viewing inventory by type Types are: Planeswalker, Sorcery, Instant, Creature, Artifact, Legendary, Green, and Land.

    Example Get URL with only accessing a specific set using set codes.

    Example Get URL with multiple options

- Statistics ^ top

Earnings, Inventory, and list reports.

Prices update once daily at 9am eastern standard time. Prices provided by TCGplayer.com

All Magic: the Gathering™ and it's respective properties references are © Wizards of the Coast.