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 token POST


    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 Currency PUT


    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 simple 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 application 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 Cards POST


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

    /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" } }

    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 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 Cards POST


    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 Condition POST


    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
    • 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 Language POST


    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 Price PUT


    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 Foil PUT


    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 (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: Adjust Acquired Date PUT


    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

  8. Inventory: View GET


    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

  9. Inventory: Stats GET


    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

  10. 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.

  11. 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 Sold POST


    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 simple 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 Value PUT


    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 simple 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 Value PUT


    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 simple 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 Date PUT


    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 simple 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 Record POST


    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

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 List POST


    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 List PUT


    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 List PUT


    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 List PUT


    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 List PUT


    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 Lists GET


    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 List GET


    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 List POST


    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 Foil PUT


    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 Sideboard PUT


    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 List POST


    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.

    Example Get URL for adding a card to 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 Watchlist POST


    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 simply 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 Threshold PUT


    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 Type PUT


    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 Record POST


    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: View GET


    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 list POST


    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 simply 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. BuyLists: Adjust Expiration Date PUT


    The user must be Auth'd to make this call. This call changes allows the user to set an expiry date on a card. Once past this date, the entry will be purged.

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

    Example Get URL for changing the expiry date of a buy list record.

  3. BuyLists: Remove Record POST


    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 Profile POST


    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: View GET


    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_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

Statistics ^ top

Earnings, Inventory, and list reports.

Prices update once daily at 9am eastern standard time.

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