A price bot is one of the quickest useful things you can build with card prices. Someone types /price Charizard 4/102 in your server and the bot replies with the card's picture, its market price and what the cheapest copy costs right now.

This guide builds one in Python with discord.py. The whole bot is about 50 lines.

What you need

  • A Discord application with a bot user, from the Discord Developer Portal, invited to your server with the applications.commands scope.
  • Python 3.10 or newer, with pip install discord.py requests.
  • An API key from your dashboard.

Keep both tokens in environment variables: DISCORD_TOKEN and TCGPRICEAPI_KEY.

One request per lookup

The bot uses the match endpoint. It takes a card name, and a collector number if the user typed one, and returns the best matching cards with their prices in the same answer. There's no separate search step, so each lookup is one request.

POST /v1/cards/match
{"name": "Charizard", "number": "4/102", "game": "Pokemon", "condition": "Near Mint", "limit": 1}

The bot

import asyncio
import os

import discord
import requests
from discord import app_commands

API = "https://tcgpriceapi.com"
HEADERS = {"X-API-Key": os.environ["TCGPRICEAPI_KEY"]}
GAMES = ["Pokemon", "Pokemon Japan", "Magic: The Gathering", "One Piece Card Game"]

client = discord.Client(intents=discord.Intents.default())
tree = app_commands.CommandTree(client)


def money(value):
    return "no recent price" if value is None else f"${value:,.2f}"


def find_card(name, number, game):
    body = {"name": name, "game": game, "condition": "Near Mint", "limit": 1}
    if number:
        body["number"] = number
    answer = requests.post(f"{API}/v1/cards/match", headers=HEADERS, json=body, timeout=30)
    answer.raise_for_status()
    candidates = answer.json()["candidates"]
    return candidates[0]["card"] if candidates else None


@tree.command(description="Look up a card's Near Mint price")
@app_commands.choices(game=[app_commands.Choice(name=game, value=game) for game in GAMES])
async def price(interaction: discord.Interaction, name: str, number: str | None = None,
                game: app_commands.Choice[str] | None = None):
    await interaction.response.defer()
    card = await asyncio.to_thread(find_card, name, number, game.value if game else "Pokemon")
    if card is None or not card["skus"]:
        await interaction.followup.send(f"I couldn't find a price for {name}.")
        return
    embed = discord.Embed(title=card["name"], description=f'{card["set"]} · {card["number"] or ""}')
    embed.set_thumbnail(url=card["image_url"])
    for sku in card["skus"][:4]:
        cheapest = sku["listing_price_low"]
        shipping = sku["listing_price_low_shipping"]
        listing = money(cheapest) + (f" + {money(shipping)} shipping" if cheapest is not None and shipping else "")
        embed.add_field(name=f'{sku["printing"]}, {sku["condition"]}',
                        value=f"Market {money(sku['market_price'])}\nCheapest listing {listing}", inline=False)
    await interaction.followup.send(embed=embed)


@client.event
async def on_ready():
    await tree.sync()
    print(f"Logged in as {client.user}")


client.run(os.environ["DISCORD_TOKEN"])

A few details worth keeping:

  • defer() tells Discord the bot is working, so a slow network never makes the command time out.
  • The API call runs in asyncio.to_thread, so one lookup never freezes the bot for everyone else.
  • A price of None means there were no recent sales. The bot says so instead of showing $0.

Making it better

  • Cache answers. Market prices refresh every 6 hours. Keep each card's answer for an hour, and a card that ten people ask about in an evening costs one request.
  • Japanese cards. Pick Pokemon Japan as the game.
  • Price history. Add a /history command that calls GET /v1/cards/{card_id}/history?timeframe=30d and posts a small chart. A 30 day chart is one request.
  • Deck totals. Let users paste a list of cards, look them up with POST /v1/cards/lookup in one request, and reply with the total.
  • Watch lists. Let members follow a card and post in a channel when its price crosses a target.

Limits and plans

Each /price is one request. Requests a minute are the limit a busy server reaches first:

Plan Requests a minute Requests a day
Free 10 100
Starter 50 1,000
Pro 100 6,000

If the bot does reach a limit, the API answers 429 with a Retry-After header. Reply with "Try again in a few seconds" rather than an error.

Free is for personal projects, such as a bot for your own friends' server. If the bot belongs to a shop, a paid community or a product, use Starter or up, which allow commercial use. Compare plans on the pricing table.