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.commandsscope. - 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
Nonemeans 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 Japanas the game. - Price history. Add a
/historycommand that callsGET /v1/cards/{card_id}/history?timeframe=30dand 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/lookupin 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.