{"openapi":"3.1.0","info":{"title":"MTG Trade Scan API","version":"1.0.0","summary":"Identify Magic cards from a binder photo. 3 free pages per day with an account, then €0.01/page.","description":"3 pages gratuites par jour avec un compte, puis 0,01 €/page. Anonymous prepaid credits (Mollie) or x402 USDC on Base remain available. Pack = €5 / 500 credits. MCP: POST /mcp (Streamable HTTP).","contact":{"url":"https://mtgtrade.com"}},"servers":[{"url":"https://mtgtrade.com","description":"Production"}],"externalDocs":{"description":"Agent discovery (llms.txt)","url":"https://mtgtrade.com/llms.txt"},"tags":[{"name":"Credits","description":"Buy a pack and retrieve the API key"},{"name":"Scan","description":"Upload an image and poll identification results"}],"paths":{"/api/v1/credits/purchase":{"post":{"tags":["Credits"],"operationId":"purchaseCredits","summary":"Create a 5€ credit pack (Mollie checkout)","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"redirect_url":{"type":"string","format":"uri","description":"URL Mollie redirects to after payment"}}}}}},"responses":{"200":{"description":"Purchase created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseCreated"}}}}}}},"/api/v1/credits/purchase/{purchaseId}":{"get":{"tags":["Credits"],"operationId":"getPurchase","summary":"Poll payment status; returns api_key once when paid","parameters":[{"name":"purchaseId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Purchase status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseStatus"}}}},"404":{"description":"Unknown purchase"}}}},"/api/v1/keys/free":{"post":{"tags":["Credits"],"operationId":"getFreeApiKey","summary":"Get a free API key for a signed-in account","responses":{"200":{"description":"Free API key created or already exists"},"401":{"description":"Sign in to MTG Trade"},"403":{"description":"Demo account not eligible"}}},"delete":{"tags":["Credits"],"operationId":"revokeFreeApiKey","summary":"Revoke the account free API key","responses":{"200":{"description":"Revocation result"},"401":{"description":"Authentication required"}}}},"/api/v1/scan":{"get":{"tags":["Scan"],"operationId":"describeScanApi","summary":"Human/agent JSON description of the API","responses":{"200":{"description":"API description"}}},"post":{"tags":["Scan"],"operationId":"startScan","summary":"Upload one image (jpeg/png/webp, max 10MB)","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"},"tcg_type":{"type":"string","enum":["mtg","pokemon","yugioh","lorcana"],"default":"mtg"}}}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanAccepted"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"No credits remaining — buy a pack","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"429":{"description":"Rate limit (10 req/min per key)"}}}},"/api/v1/scan/{jobId}":{"get":{"tags":["Scan"],"operationId":"getScanJob","summary":"Poll job until processed or failed","security":[{"bearerAuth":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanJob"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Job not found for this key"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mgt_","description":"API key from GET /api/v1/credits/purchase/{id} after payment"}},"schemas":{"PurchaseCreated":{"type":"object","required":["purchase_id","status","poll"],"properties":{"purchase_id":{"type":"string"},"payment_url":{"type":["string","null"],"format":"uri"},"status":{"type":"string","enum":["pending","paid"]},"poll":{"type":"string"}}},"PurchaseStatus":{"type":"object","required":["status","credits","already_revealed"],"properties":{"status":{"type":"string","enum":["pending","paid","failed","expired","canceled"]},"api_key":{"type":["string","null"]},"credits":{"type":"integer"},"already_revealed":{"type":"boolean"}}},"ScanAccepted":{"type":"object","required":["job_id","credits_remaining","poll"],"properties":{"job_id":{"type":"string","format":"uuid"},"credits_remaining":{"type":"integer"},"poll":{"type":"string"}}},"PaymentRequired":{"type":"object","properties":{"error":{"type":"string"},"credits_remaining":{"type":"integer"},"purchase_url":{"type":"string","format":"uri"}}},"ScanJob":{"type":"object","required":["job_id","status","credits_remaining"],"properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","processed","failed"]},"result":{"$ref":"#/components/schemas/ScanResult"},"error":{"type":["string","null"]},"credits_remaining":{"type":"integer"}}},"ScanResult":{"type":"object","required":["cards"],"properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/ScanCard"}}}},"ScanCard":{"type":"object","properties":{"name":{"type":["string","null"]},"edition":{"type":["string","null"]},"collector_number":{"type":["string","null"]},"price_eur":{"type":["number","null"]},"confidence":{"type":["number","null"]},"image_url":{"type":["string","null"]},"scryfall_id":{"type":["string","null"]}}}}},"x-mtg-trade":{"price_eur_per_scan":0.01,"free_pages_per_day_with_account":3,"pack_price_eur":5,"pack_credits":500,"mcp":"/mcp","mcp_server_card":"/mcp/server-card","x402_headers":["PAYMENT-REQUIRED","PAYMENT-SIGNATURE","PAYMENT-RESPONSE"]}}