MTG Sea API Documentation

Welcome to the Price API documentation. The Price API allows you to access prices in a simple, programmatic way while using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information.

Requests

Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests must be made using the HTTPS protocol so that traffic is encrypted.

HTTP Methods

Method Usage
GET For simple retrieval of information. Read-only and will not affect any objects.
DELETE To destroy a resource and remove it from your account.
PUT To update existing resource information.
POST To create new objects.

HTTP Status Codes

The API returns standard HTTP status codes. 200-range indicates success, 400-range indicates client errors, and 500-range indicates server errors.

Code Description
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
404 Not Found The requested resource doesn't exist.
429 Too Many Requests Too many requests hit the API too quickly.
500-504 Server Errors Something went wrong on our end.

Authentication

The API uses API keys for authentication. Include your API key in the request headers for every request.

curl -X GET 'https://api.chimneyimp.com/api/v2/products/...' \ -H 'x-api-key: $API_KEY'

Meta

The response may contain a meta object with information about the response itself. 

{
  "meta": {
    "total_pages": 17,
    "current_page_count": 10,
    "total_count": 170,
    "prev_page": 2,
    "next_page": 3
  }
}

Links & Pagination

By default, 100 objects are returned per page. Use ?page=:number to view a different page. The pagination object contains pagination information when needed. 

{
    "pagination": {
        "current_page": 2,
        "total_pages": 8,
        "total_count": 712,
        "per_page": 100
    }
}

Rate Limit

Requests are limited to 1 per second per IP address. Rate limit information is included in response headers.

Rate Limit Exceeded Response

{
    "error": "Too Many Requests",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 1
}

Categories

Endpoint URL https://api/api/v2/categories
Purpose Get all categories in the TCG catalog
Method GET
Parameters N/A
Response Object

Status code: 200 | OK

{
  "success": true,
  "results": [
    {
      "id": 2,
      "name": "Magic: The Gathering",
      "tcg_category_id": 1
    },
    {
      "id": 4,
      "name": "Lorcana Tcg",
      "tcg_category_id": 71
    },
    {
      "id": 5,
      "name": "Grand Archive",
      "tcg_category_id": 74
    },
    {
      "id": 6,
      "name": "Pokemon",
      "tcg_category_id": 3
    }
  ]
}
Error Object Status code: 400 | Bad Request

Set Names

Endpoint URL https://api.mtg-sea.com/api/v2/variations/set_codes?tcg_category_id=:id
Purpose Get all set_codes in the MTG multiverses via tcg category id
Method GET
Parameters tcg_category_id=numeric id
Response Object

Status code: 200 | OK

{
  "success": true,
  "results": [
    {
      "id": 247,
      "name": "Ixalan",
      "set_code": "xln",
      "tcg_set_name": null,
      "tcg_group_id": 2043,
      "tcg_set_code": "xln"
    },
    {
      "id": 57,
      "name": "Foundations",
      "set_code": "fdn",
      "tcg_set_name": null,
      "tcg_group_id": 23556,
      "tcg_set_code": "fdn"
    }
  ]
}
Error Object Status code: 400 | Bad Request

Products by Set Code

Endpoint URL https://api.mtg-sea.com/api/v2/products/cards/:set_code
Purpose Get products by set code with pagination support
Method GET
Parameters
  • set_code (required) - The set code to fetch products for
  • page (optional) - Page number for pagination (default: 1)
  • created_after (optional) - Filter products created after this date (format: YYYY-MM-DD)
Headers x-api-key: Your API Key
Example Request 
curl --location 'https://api.mtg-sea.com/api/v2/products/cards/who?created_after=2025-01-01' \
--header 'x-api-key: YOUR_API_KEY'
Response Object

Status code: 200 | OK

{
  "success": true,
  "results": [
    {
      "id": 83149,
      "name": "The Lux Foundation Library",
      "description": "Players have no maximum hand size...",
      "price": "0.79",
      "artist": "",
      "updated_at": "2025-01-11T01:47:50.214+08:00",
      "multiverse_id": "634266",
      "price_updated_at": "2025-01-11T01:47:50.214+08:00",
      "tcg_product_id": 496083,
      "foil_price": "0.0",
      "rarity": "Tokens",
      "eur_avg_price": "0.0",
      "eur_price_updated_at": null,
      "ck_price": "0.35",
      "ck_foil_price": "0.0",
      "ck_price_updated_at": "2025-01-10T03:51:19.416+08:00",
      "ck_external_id": null
    },...
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 4,
    "total_count": 397,
    "per_page": 100
  }
}
Error Object Status code: 400 | Bad Request

Products by TCG Group ID

Endpoint URL https://api.mtg-sea.com/api/v2/products/cards_by_tcg_group_id/:tcg_group_id
Purpose Get products by TCG group ID with pagination support
Method GET
Parameters
  • tcg_group_id (required) - The TCG group ID to fetch products for
  • page (optional) - Page number for pagination (default: 1)
  • created_after (optional) - Filter products created after this date (format: YYYY-MM-DD)
Headers x-api-key: Your API Key
Example Request 
curl --location 'https://api.mtg-sea.com/api/v2/products/cards_by_tcg_group_id/1?created_after=2025-01-01' \
--header 'x-api-key: YOUR_API_KEY'
Response Object

Status code: 200 | OK

{
    "success": true,
    "results": [
        {
            "id": 1,
            "name": "Abundance",
            "description": "If you would draw a card, you may ...",
            "price": "1.62",
            "artist": "",
            "updated_at": "2025-05-03T01:55:45.078+08:00",
            "multiverse_id": null,
            "price_updated_at": "2025-05-03T01:55:45.078+08:00",
            "tcg_product_id": 15023,
            "tcg_image_url": "https://tcgplayer-cdn.tcgplayer.com/product/15023_200w.jpg",
            "foil_price": "64.07",
            "eur_avg_price": "0.0",
            "eur_price_updated_at": null,
            "ck_price": "0.0",
            "ck_foil_price": "0.0",
            "ck_price_updated_at": null,
            "ck_external_id": null,
            "attributes": {
                "R": "R",
                "249": "249",
                "Enchantment": "Enchantment",
                "10th Edition": "10th Edition"
            }
        },...
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 4,
        "total_count": 397,
        "per_page": 100
    }
}
Error Object Status code: 400 | Bad Request

Price by Set Code

Endpoint URL https://api.mtg-sea.com/api/v2/products/pricing/:set_code
Purpose Get product prices by set code with pagination support
Method GET
Parameters
  • set_code (required) - The set code to fetch prices for
  • page (optional) - Page number for pagination (default: 1)
Headers x-api-key: Your API Key
Example Request 
curl --location 'https://api.mtg-sea.com/api/v2/products/pricing/who' \
--header 'x-api-key: YOUR_API_KEY'
Response Object

Status code: 200 | OK

{
  "success": true,
  "results": [
    {
      "id": 83149,
      "price": "0.79",
      "updated_at": "2025-01-11T01:47:50.214+08:00",
      "multiverse_id": "634266",
      "price_updated_at": "2025-01-11T01:47:50.214+08:00",
      "tcg_product_id": 496083,
      "foil_price": "0.0",
      "eur_avg_price": "0.0",
      "eur_price_updated_at": null,
      "ck_price": "0.35",
      "ck_foil_price": "0.0",
      "ck_price_updated_at": "2025-01-10T03:51:19.416+08:00",
      "ck_external_id": null
    },...
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 4,
    "total_count": 397,
    "per_page": 100
  }
}
Error Object Status code: 400 | Bad Request

Price by TCG Group ID

Endpoint URL https://api.mtg-sea.com/api/v2/products/pricing_by_tcg_group_id/:tcg_group_id
Purpose Get product prices by TCG group ID with pagination support
Method GET
Parameters
  • tcg_group_id (required) - The TCG group ID to fetch prices for
  • page (optional) - Page number for pagination (default: 1)
Headers x-api-key: Your API Key
Example Request 
curl --location 'https://api.mtg-sea.com/api/v2/products/pricing_by_tcg_group_id/2809?page=2' \
--header 'x-api-key: YOUR_API_KEY'
Response Object

Status code: 200 | OK

{
    "success": true,
    "results": [
        {
            "id": 57721,
            "multiverse_id": null,
            "tcg_product_id": 239586,
            "price": "0.0",
            "foil_price": "0.4",
            "price_updated_at": "2025-05-24T23:15:33.982+08:00",
            "updated_at": "2025-05-24T23:15:33.982+08:00",
            "eur_avg_price": "0.0",
            "eur_price_updated_at": null,
            "ck_price": "0.0",
            "ck_foil_price": "0.0",
            "ck_price_updated_at": null,
            "ck_external_id": null
        },...
    ],
    "pagination": {
        "current_page": 2,
        "total_pages": 8,
        "total_count": 712,
        "per_page": 100
    }
}
Error Object Status code: 400 | Bad Request

Latest Price Updates

Endpoint URL https://api.mtg-sea.com/api/v2/products/latest_prices_x_days
Purpose Get products with price updates within the specified number of days
Method GET
Parameters
  • past_x_days (required) - Number of days to look back for price updates. Max 3 days.
  • page (optional) - Page number for pagination (default: 1)
Headers x-api-key: Your API Key
Example Request 
curl --location 'https://api.mtg-sea.com/api/v2/products/latest_prices_x_days?past_x_days=1' \
--header 'x-api-key: YOUR_API_KEY'
Response Object

Status code: 200 | OK

{
    "success": true,
    "results": [
        {
            "id": 140164,
            "multiverse_id": null,
            "tcg_product_id": 482406,
            "price": "15.24",
            "foil_price": "0.0",
            "price_updated_at": "2025-05-24T17:24:19.830+08:00",
            "updated_at": "2025-05-24T17:24:19.830+08:00",
            "eur_avg_price": "0.0",
            "eur_price_updated_at": null,
            "ck_price": "0.0",
            "ck_foil_price": "0.0",
            "ck_price_updated_at": null,
            "ck_external_id": null
        },...
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 3,
        "total_count": 236,
        "per_page": 100
    }
}
Error Object Status code: 400 | Bad Request