{ "openapi": "3.1.0", "info": { "title": "Cryptocardium REST API", "summary": "Issue, fund, control and reconcile no-KYC crypto-funded Visa and Mastercard cards.", "description": "REST v1 surface for the Cryptocardium card programme. Fifty endpoints across accounts, sessions, API keys, balance, top-ups, cards, transactions, activity, withdrawals, disputes, webhooks, support and system. All POST and PATCH operations accept an Idempotency-Key header. Collection reads are paginated. Every response carries a structured error code on non-2xx.\n\nAuthentication: bearer API key in the Authorization header, or OAuth 2.1 bearer token for agents (see /.well-known/oauth-authorization-server).", "version": "1.0.0", "termsOfService": "https://cryptocardium.com/legal", "contact": { "name": "Cryptocardium", "url": "https://cryptocardium.com/contact" }, "license": { "name": "Proprietary", "url": "https://cryptocardium.com/legal" } }, "servers": [ { "url": "https://api.cryptocardium.com/v1", "description": "Production" } ], "externalDocs": { "description": "Full developer documentation", "url": "https://cryptocardium.com/docs" }, "tags": [ { "name": "Accounts" }, { "name": "API keys" }, { "name": "Balance" }, { "name": "Top-ups" }, { "name": "Cards" }, { "name": "Transactions" }, { "name": "Activity" }, { "name": "Withdrawals" }, { "name": "Disputes" }, { "name": "Webhooks" }, { "name": "Support" }, { "name": "System" } ], "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Bearer API key. Create at /api-settings." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.1 for AI agents. See /.well-known/oauth-authorization-server. Supports Dynamic Client Registration (RFC 7591).", "flows": { "authorizationCode": { "authorizationUrl": "https://cryptocardium.com/oauth/authorize", "tokenUrl": "https://cryptocardium.com/oauth/token", "scopes": { "account:read": "Read account state and 2FA status", "balance:read": "Read current balance and balance history", "topup:create": "Create top-ups", "topup:read": "Read top-up state", "card:read": "Read card metadata", "card:issue": "Issue new cards", "card:control": "Freeze, unfreeze, set limits, MCC and geo rules", "card:reveal_pan": "Reveal full PAN and CVV (sensitive)", "transaction:read": "Read transactions and ISO 8583 auth details", "withdrawal:create": "Withdraw to external wallets", "withdrawal:read": "Read withdrawal state", "dispute:write": "File disputes and attach evidence", "webhook:write": "Manage webhook subscriptions", "system:read": "Read system health and your rate limits" } } } } }, "schemas": { "Error": { "type": "object", "required": ["error", "message"], "properties": { "error": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable message" }, "request_id": { "type": "string" } } }, "Pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"] }, "has_more": { "type": "boolean" } } }, "Card": { "type": "object", "properties": { "id": { "type": "string", "example": "card_8f3a91b7c4d2" }, "bin": { "type": "string", "example": "489517" }, "last4": { "type": "string", "example": "4218" }, "brand": { "type": "string", "enum": ["visa", "mastercard"] }, "type": { "type": "string", "enum": ["virtual", "physical"] }, "status": { "type": "string", "enum": ["active", "frozen", "cancelled"] }, "balance_usd": { "type": "number" }, "wallet": { "type": "object", "properties": { "apple_pay": { "type": "string", "enum": ["ready", "pending", "unsupported"] }, "google_pay": { "type": "string", "enum": ["ready", "pending", "unsupported"] } } } } }, "Topup": { "type": "object", "properties": { "id": { "type": "string" }, "asset": { "type": "string", "example": "USDT" }, "chain": { "type": "string", "example": "tron" }, "deposit_address": { "type": "string" }, "amount_usd": { "type": "number" }, "status": { "type": "string", "enum": ["awaiting", "confirming", "completed", "cancelled", "error"] }, "txid": { "type": ["string", "null"] } } } } }, "security": [{ "bearerApiKey": [] }, { "oauth2": [] }], "paths": { "/accounts": { "post": { "tags": ["Accounts"], "operationId": "create_account", "summary": "Create a new account", "description": "No KYC, no documents. Returns a bearer session.", "responses": { "201": { "description": "Created" } } } }, "/sessions": { "post": { "tags": ["Accounts"], "operationId": "sign_in", "summary": "Sign in with email and password", "responses": { "200": { "description": "OK" } } }, "delete": { "tags": ["Accounts"], "operationId": "sign_out", "summary": "Sign out the current session", "responses": { "204": { "description": "No content" } } } }, "/accounts/me": { "get": { "tags": ["Accounts"], "operationId": "get_account", "summary": "Return current account, balance and 2FA state", "responses": { "200": { "description": "OK" } } }, "patch": { "tags": ["Accounts"], "operationId": "update_account", "summary": "Update account email, password, notifications", "responses": { "200": { "description": "OK" } } } }, "/accounts/me/totp": { "post": { "tags": ["Accounts"], "operationId": "enable_2fa", "summary": "Enrol an authenticator (returns secret + URI)", "responses": { "200": { "description": "OK" } } }, "delete": { "tags": ["Accounts"], "operationId": "disable_2fa", "summary": "Disable 2FA (requires password and valid code)", "responses": { "204": { "description": "No content" } } } }, "/api_keys": { "get": { "tags": ["API keys"], "operationId": "list_api_keys", "responses": { "200": { "description": "OK" } } }, "post": { "tags": ["API keys"], "operationId": "create_api_key", "responses": { "201": { "description": "Created" } } } }, "/api_keys/{id}": { "delete": { "tags": ["API keys"], "operationId": "revoke_api_key", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "204": { "description": "No content" } } } }, "/balance": { "get": { "tags": ["Balance"], "operationId": "get_balance", "summary": "Current USDT balance", "responses": { "200": { "description": "OK" } } } }, "/balance/history": { "get": { "tags": ["Balance"], "operationId": "get_balance_history", "responses": { "200": { "description": "OK" } } } }, "/topups": { "post": { "tags": ["Top-ups"], "operationId": "create_topup", "summary": "Create a top-up: returns deposit address + QR", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topup" } } } } } }, "get": { "tags": ["Top-ups"], "operationId": "list_topups", "responses": { "200": { "description": "OK" } } } }, "/topups/{id}": { "get": { "tags": ["Top-ups"], "operationId": "get_topup", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topup" } } } } } } }, "/topups/{id}/cancel": { "post": { "tags": ["Top-ups"], "operationId": "cancel_topup", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards": { "get": { "tags": ["Cards"], "operationId": "list_cards", "responses": { "200": { "description": "OK" } } }, "post": { "tags": ["Cards"], "operationId": "issue_card", "summary": "Issue a new card (virtual or physical)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } } } } }, "/cards/{id}": { "get": { "tags": ["Cards"], "operationId": "get_card", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } } } } }, "/cards/{id}/pan": { "get": { "tags": ["Cards"], "operationId": "reveal_pan", "summary": "Full PAN + CVV (sensitive, single use, audited)", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } }, "security": [{ "oauth2": ["card:reveal_pan"] }, { "bearerApiKey": [] }] } }, "/cards/{id}/replace": { "post": { "tags": ["Cards"], "operationId": "replace_card", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards/{id}/load": { "post": { "tags": ["Cards"], "operationId": "load_card", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards/{id}/unload": { "post": { "tags": ["Cards"], "operationId": "unload_card", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards/{id}/freeze": { "post": { "tags": ["Cards"], "operationId": "freeze_card", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards/{id}/unfreeze": { "post": { "tags": ["Cards"], "operationId": "unfreeze_card", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards/{id}/cancel": { "post": { "tags": ["Cards"], "operationId": "cancel_card", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards/{id}/limits": { "patch": { "tags": ["Cards"], "operationId": "set_card_limits", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards/{id}/mcc": { "patch": { "tags": ["Cards"], "operationId": "set_mcc_rules", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards/{id}/geo": { "patch": { "tags": ["Cards"], "operationId": "set_card_geo", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/transactions": { "get": { "tags": ["Transactions"], "operationId": "list_transactions", "responses": { "200": { "description": "OK" } } } }, "/transactions/{id}": { "get": { "tags": ["Transactions"], "operationId": "get_transaction", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/cards/{id}/transactions": { "get": { "tags": ["Transactions"], "operationId": "list_card_transactions", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/transactions/{id}/auth": { "get": { "tags": ["Transactions"], "operationId": "get_auth_details", "summary": "Raw ISO 8583 auth fields", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/activity": { "get": { "tags": ["Activity"], "operationId": "get_activity", "responses": { "200": { "description": "OK" } } } }, "/audit_log": { "get": { "tags": ["Activity"], "operationId": "get_audit_log", "responses": { "200": { "description": "OK" } } } }, "/withdrawals": { "post": { "tags": ["Withdrawals"], "operationId": "withdraw", "responses": { "201": { "description": "Created" } } }, "get": { "tags": ["Withdrawals"], "operationId": "list_withdrawals", "responses": { "200": { "description": "OK" } } } }, "/withdrawals/{id}": { "get": { "tags": ["Withdrawals"], "operationId": "get_withdrawal", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/disputes": { "post": { "tags": ["Disputes"], "operationId": "file_dispute", "responses": { "201": { "description": "Created" } } }, "get": { "tags": ["Disputes"], "operationId": "list_disputes", "responses": { "200": { "description": "OK" } } } }, "/disputes/{id}": { "get": { "tags": ["Disputes"], "operationId": "get_dispute", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/disputes/{id}/evidence": { "post": { "tags": ["Disputes"], "operationId": "add_dispute_evidence", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/webhooks": { "get": { "tags": ["Webhooks"], "operationId": "list_webhooks", "responses": { "200": { "description": "OK" } } }, "post": { "tags": ["Webhooks"], "operationId": "create_webhook", "responses": { "201": { "description": "Created" } } } }, "/webhooks/{id}": { "patch": { "tags": ["Webhooks"], "operationId": "update_webhook", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } }, "delete": { "tags": ["Webhooks"], "operationId": "delete_webhook", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "204": { "description": "No content" } } } }, "/webhooks/{id}/replay/{eid}": { "post": { "tags": ["Webhooks"], "operationId": "replay_webhook", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "eid", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "OK" } } } }, "/tickets": { "post": { "tags": ["Support"], "operationId": "open_ticket", "responses": { "201": { "description": "Created" } } }, "get": { "tags": ["Support"], "operationId": "list_tickets", "responses": { "200": { "description": "OK" } } } }, "/system/health": { "get": { "tags": ["System"], "operationId": "get_system_health", "responses": { "200": { "description": "OK" } } } }, "/system/limits": { "get": { "tags": ["System"], "operationId": "get_limits", "responses": { "200": { "description": "OK" } } } } } }