{"openapi":"3.0.3","info":{"title":"EZCards AI Agent API","description":"Purchase and manage reloadable virtual Visas funded with cryptocurrency. No KYC required. Designed for AI agent consumption.","version":"1.0.0","contact":{"url":"https://ezcards.cc"}},"servers":[{"url":"https://ezcards.cc/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your EZCards agent API key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Product":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"card_type":{"type":"string"},"currency":{"type":"string"},"activation_fee_usd":{"type":"number","description":"Activation fee in dollars"},"min_load_usd":{"type":"number","description":"Minimum load in dollars"},"max_load_usd":{"type":"number","description":"Maximum load in dollars"},"exchange_fee_pct":{"type":"number"},"supports_apple_pay":{"type":"boolean"},"supports_google_pay":{"type":"boolean"},"region":{"type":"string","nullable":true}}},"Currency":{"type":"object","properties":{"chain_id":{"type":"string","description":"Chain identifier to use in API calls"},"label":{"type":"string","description":"Human-readable label"}}},"PaymentInfo":{"type":"object","properties":{"address":{"type":"string","description":"Crypto address to send payment to"},"amount":{"type":"number","description":"Amount of crypto to send"},"amount_usd":{"type":"number","description":"Equivalent USD amount"},"chain":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"CardDetails":{"type":"object","properties":{"card_number":{"type":"string"},"cvv":{"type":"string"},"expiry":{"type":"string"},"cardholder_name":{"type":"string"},"billing_address":{"type":"string","nullable":true}}}}},"paths":{"/products":{"get":{"operationId":"listProducts","summary":"List available card products with pricing","responses":{"200":{"description":"Product list","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"markup_percent":{"type":"number"}}}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/currencies":{"get":{"operationId":"listCurrencies","summary":"List supported crypto payment methods","responses":{"200":{"description":"Currency list","content":{"application/json":{"schema":{"type":"object","properties":{"currencies":{"type":"array","items":{"$ref":"#/components/schemas/Currency"}}}}}}}}}},"/cards/purchase":{"post":{"operationId":"purchaseCard","summary":"Purchase a new virtual Visa","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id","load_amount_usd","crypto_chain","cardholder"],"properties":{"product_id":{"type":"integer","description":"Product ID from /products"},"load_amount_usd":{"type":"number","description":"Amount in USD dollars to load"},"crypto_chain":{"type":"string","description":"Chain ID from /currencies (e.g. usdt_trx)"},"cardholder":{"type":"object","required":["first_name","last_name","email"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Order created — send crypto to the payment address","content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string"},"payment":{"$ref":"#/components/schemas/PaymentInfo"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{orderId}":{"get":{"operationId":"getCardDetails","summary":"Get card details and order status","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"},"description":"Order UUID or order number (ORD-XXXXXX)"}],"responses":{"200":{"description":"Order and card details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"order_number":{"type":"string"},"status":{"type":"string"},"status_label":{"type":"string"},"load_amount_usd":{"type":"number","nullable":true},"total_usd":{"type":"number"},"balance_usd":{"type":"number","nullable":true},"card":{"$ref":"#/components/schemas/CardDetails"},"payment":{"$ref":"#/components/schemas/PaymentInfo"}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{orderId}/balance":{"get":{"operationId":"getCardBalance","summary":"Check card balance","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Card balance","content":{"application/json":{"schema":{"type":"object","properties":{"balance_usd":{"type":"number"},"last_updated":{"type":"string","format":"date-time"}}}}}}}}},"/cards/{orderId}/reload":{"post":{"operationId":"reloadCard","summary":"Reload an existing card with more funds","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_usd","crypto_chain"],"properties":{"amount_usd":{"type":"number","description":"Reload amount in USD dollars"},"crypto_chain":{"type":"string","description":"Chain ID from /currencies"}}}}}},"responses":{"201":{"description":"Reload order created — send crypto to the payment address","content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string"},"order_number":{"type":"string"},"original_order_id":{"type":"string"},"status":{"type":"string"},"payment":{"$ref":"#/components/schemas/PaymentInfo"}}}}}}}}},"/developers/register":{"post":{"operationId":"registerApiKey","summary":"Register for a new API key","description":"Issues a new API key for the given email. No approval required. Rate-limited to 5 registrations per IP per hour and a maximum of 3 active keys per email.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","description":"Optional label for the key"}}}}}},"responses":{"201":{"description":"API key created. Save the key — it will not be shown again.","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","description":"Full API key (starts with ezc_live_)"},"key_prefix":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded"}}}},"/developers/keys":{"get":{"operationId":"listApiKeys","summary":"List your API keys","description":"Returns all API keys associated with the caller. Never returns the full key; only the prefix.","responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"key_prefix":{"type":"string"},"label":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"401":{"description":"Missing or invalid API key"}}}},"/developers/keys/{id}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Key revoked"},"401":{"description":"Missing or invalid API key"},"404":{"description":"Key not found"}}}}}}