{"data":{"@kind":"guide","slug":"build-a-discord-bot","title":"Build a Discord bot using Cambridge TCG data","subtitle":"Slash command → keyed structural lookup → honest embed.","intro":"This guide builds a card-identity lookup bot. The public response does not currently publish legacy source-derived prices, images, or history, so the embed names those absences instead of filling them from storage.","audiences":["hobbyist_coder","agent"],"prerequisites":["A Discord bot registered (via discord.com/developers)","Node.js or Python (or any language) with HTTP + Discord SDK"],"estimated_minutes":20,"step_count":4,"steps":[{"step_number":1,"title":"Register a /card slash command","instruction":"Your bot accepts `/card <sku>`. When the user invokes it, your handler receives the SKU string. The handler will call Cambridge TCG with that SKU.","what_to_do_with_it":"Most Discord SDKs have a slash-command registration helper. The exact syntax depends on your language — discord.py / discord.js / serenity all support it."},{"step_number":2,"title":"Call /api/v1/universal/card/[sku] from your handler","instruction":"Send a User-Agent identifying your bot, follow the response's Cache-Control header, and request only a user's concrete SKU. The response carries structural name, set, rarity, and rights fields; price and image are null while source rights are unresolved.","curl":"curl -H 'User-Agent: my-discord-bot/1.0 (admin@me.example)' \\\n  https://cambridgetcg.com/api/v1/universal/card/op-op01-001-ja","expected_response_shape":"{ \"@kind\": \"card\", \"@content_hash\": \"sha256:...\", \"sku\": \"...\", \"rights\": { \"aggregate\": \"NOASSERTION\", ... }, \"price\": null, \"name\": { \"natural_token\": \"...\", \"resolved_lang\": \"en\" }, \"image_url\": null, \"rarity\": { \"natural_label\": \"leader\", ... }, \"in_set\": { \"target_natural_token\": \"OP01\", ... } }","what_to_do_with_it":"Extract `name.natural_token`, `rarity.natural_label`, and `in_set.target_natural_token`. Render price/image as unavailable; do not substitute a legacy URL or magnitude from another response."},{"step_number":3,"title":"Render a Discord embed","instruction":"Build an embed with the card's name as title and its set/rarity as fields. Include a footer with the aggregate rights declaration and a link back to the exact Cambridge TCG resource.","what_to_do_with_it":"Recommended footer: 'Structural reference via Cambridge TCG; aggregate rights NOASSERTION; upstream rights retained; price/image withheld.'"},{"step_number":4,"title":"Cache + handle errors gracefully","instruction":"Wrap the lookup in a cache that follows the response headers. On 404, respond with a helpful search hint. On 429 or a network error, use a labelled cached structural response or state that data is unavailable.","what_to_do_with_it":"Substrate-honest about your bot's own state: if the API is unreachable, say so. Do not fabricate a price or image from an older response."}],"gotchas":[{"title":"SKU format matters","description":"Cambridge TCG SKUs are canonical: `<game>-<set>-<number>-<lang>[-<variant>]`, lowercase. If the user types `OP01-001`, normalize it to `op-op01-001-ja` (or the language your bot defaults to) before calling. The CTCG-SKU-v1 specification text is CC0; the @cambridge-tcg/sku parser is a private workspace package, not published to npm; repository code is Apache-2.0 per LICENSE, and the repository itself is public."},{"title":"Don't bulk-fetch on bot startup","description":"Some bots try to pre-warm a local cache by walking all SKUs at boot. Don't. /data/catalog.jsonl is status-only while bulk publication is paused; use keyed search only for a user's concrete request.","fix":"Query /api/v1/search/cards for the requested identifier and cache only that result."},{"title":"Images are withheld","description":"The public universal-card route returns image_url: null. Storage or a previously seen CDN URL is not permission to republish the image."},{"title":"Do not add a CardRush history command","description":"CardRush history is withheld from public, signed-in, and bearer-token delivery. The signed-in status door returns HTTP 503 and no observations; authentication does not create source permission."}],"next_guide":{"slug":"handle-staleness","title":"Handle staleness gracefully","url":"/api/v1/guides/handle-staleness","html_url":"/agents/guides/handle-staleness"},"see_also":[{"label":"Universal card example","href":"/api/v1/examples/universal-card"},{"label":"Cite Cambridge TCG","href":"/api/v1/guides/cite-cambridge-tcg"},{"label":"CTCG-SKU-v1 identity schema","href":"/spec/v1/SkuIdentity.schema.json"}],"last_verified":"2026-07-12","feedback":{"kind":"guide-feedback","endpoint":"/api/v1/feedback","body_template":{"kind":"guide-feedback","guide_slug":"build-a-discord-bot","step_number":"<which step had the issue, or null for whole-guide feedback>","observation":"<what you observed>","expected":"<what you expected>","reporter_contact":"<your email>"}},"html_sibling":"/agents/guides/build-a-discord-bot"},"_meta":{"spec_version":"1","endpoint":"/api/v1/guides/[slug]","retrieved_at":"2026-11-18T21:26:13.996Z","as_of":"2026-11-18T21:26:13.996Z","sources":["ctcg-derived"],"freshness_seconds":86400,"license":"CC0-1.0","request_id":"req_289f52ec-9f5","deprecation":null,"next_link":null,"self_reference":{"this_endpoint":"/api/v1/guides/[slug]","contains_self":true},"source_license":["cc0"]}}