{"openapi":"3.1.0","info":{"title":"1Gogh Exchange Exchange API","version":"1.2","description":"Our REST API version 1.2 provides programmatic access to the platform\u2019s trading engine API endpoints. We strongly recommend that our new customers use API version 1.2 to get the best trading experience. We also recommend that our current traders switch to the newest version 1.2.\n\n## Getting your API key\n\nThe Exchange API authenticates with a Bearer token. Log in and open [Profile \u2192 API Tokens](\/user\/api-tokens) to create one \u2014 the token value is shown once at creation, so store it securely. Send it with every request in the `Authorization: Bearer <token>` header.\n\nMerchant acquiring uses separate `pk_live_` HMAC keys (see the Merchant Acquiring document) \u2014 the two credential systems are not interchangeable.\n\n## DateTime Format\n\nAll timestamps are returned in ISO 8601 format or UNIX timestamp in milliseconds (UTC).\n\nExample: `\"2021-06-03T10:20:49.315Z\"` or `\"1614815872000\"`.\n\n## Number Format\n\nAll currency data, e.g., price, amount, fee, etc., should be precision numbers and have a string representation. Example: `\"20.4383003\"`.\n\n## Rate Limiting\n\nThe following Rate Limits are applied:\n\n- for the Market data, the limit is 20 requests per second for one IP;\n- for Trading, the limit is 50 requests per second for one user;\n- for other requests, the limit is 10 requests per second for one user.\n\nSignificantly exceeding the Rate Limits can lead to suspension.\n\n## Best Practices\n\nThe development team does its best to bring the best trading experience to API users. This manual contains a set of best practices for using the API as efficiently as possible.\n\n### HTTP Persistent Connection\n\nThe underlying TCP connection is kept active for multiple requests\/responses. Subsequent requests will result in reduced latency as the TCP handshaking process is no longer required.\n\nIf you use the HTTP 1.0 client, please ensure it supports the Keep-Alive directive and submit the \"Connection: Keep-Alive\" header with your request.\n\nKeep-Alive is a part of the HTTP\/1.1 or HTTP\/2 protocol and is enabled by default on compliant clients. However, you will have to ensure your implementation does not set other values as the connection header.\n\n## HTTP Status Codes\n\n- `200` OK. Successful request\n- `422` Bad Request. Returns JSON with the error message\n- `401` Unauthorized. Authorization is required or has been failed\n- `403` Forbidden. Action is forbidden\n- `404` Not Found. Data requested cannot be found\n- `429` Too Many Requests. Your connection has been rate limited\n- `500` Internal Server. Internal Server Error\n- `503` Service Unavailable. Service is down for maintenance\n- `504` Gateway Timeout. Request timeout expired\n\n## AI & MCP\n\nThis reference is a machine-readable **OpenAPI 3.1** document: https:\/\/exchange.1gogh.io\/api-docs\/exchange.json \u2014 plug it into AI tools directly, no extra services required.\n\n**MCP** (Claude Desktop, Cursor and other MCP clients) \u2014 run any open-source OpenAPI-to-MCP bridge, for example [@ivotoby\/openapi-mcp-server](https:\/\/www.npmjs.com\/package\/@ivotoby\/openapi-mcp-server):\n\n```json\n{\n  \"mcpServers\": {\n    \"1gogh-exchange-exchange-api\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ivotoby\/openapi-mcp-server\"],\n      \"env\": {\n        \"API_HEADERS\": \"Authorization:Bearer <your_api_token>\",\n        \"API_BASE_URL\": \"https:\/\/exchange.1gogh.io\/api\/v1\",\n        \"OPENAPI_SPEC_PATH\": \"https:\/\/exchange.1gogh.io\/api-docs\/exchange.json\"\n      }\n    }\n  }\n}\n```\n\n**Any LLM** \u2014 fetch the document above and pass it as context: it describes every endpoint, parameter and schema."},"servers":[{"url":"https:\/\/exchange.1gogh.io\/api\/v1","description":"API server"}],"security":[{"http":[]}],"paths":{"\/api\/bridge\/address-book":{"get":{"operationId":"bridge.address-book.index","summary":"Active address book entries","tags":["AddressBook"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"entries":{"type":"array","items":{}}},"required":["entries"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"post":{"operationId":"bridge.address-book.store","summary":"Add an address. Mandatory TOTP (SPEC \u00a75\/\u00a710)","tags":["AddressBook"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StoreAddressBookRequest"}}}},"responses":{"201":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"entry":{"type":"array","items":{}}},"required":["entry"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"description":"Add an address. Mandatory TOTP (SPEC \u00a75\/\u00a710) \u2014 2FA must be enabled"}},"\/api\/bridge\/auth\/email\/request-otp":{"post":{"operationId":"bridge.auth.email.request","summary":"Send a one-time login code to the given email","tags":["Auth"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RequestEmailOtpRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string","const":"We sent a verification code to your email."},"resend_in":{"type":"integer"}},"required":["message","resend_in"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/api\/bridge\/auth\/email\/verify":{"post":{"operationId":"bridge.auth.email.verify","summary":"Verify the emailed code and sign the user in (registering on first login)","tags":["Auth"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/VerifyEmailOtpRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"token":{"type":"string"},"user":{"type":"array","items":{}}},"required":["token","user"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/api\/bridge\/auth\/telegram":{"post":{"operationId":"bridge.auth.telegram","summary":"Sign in via Telegram Mini App initData or Login Widget payload","tags":["Auth"],"requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TelegramLoginRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"token":{"type":"string"},"user":{"type":"array","items":{}}},"required":["token","user"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/api\/bridge\/auth\/google":{"post":{"operationId":"bridge.auth.google","summary":"Sign in via a Google id_token","tags":["Auth"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/GoogleLoginRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"token":{"type":"string"},"user":{"type":"array","items":{}}},"required":["token","user"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/api\/bridge\/auth\/logout":{"post":{"operationId":"bridge.auth.logout","summary":"Revoke the current access token","tags":["Auth"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string","const":"Signed out."}},"required":["message"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/balance":{"get":{"operationId":"bridge.balance","description":"Returns the caller's balance as `pending` (deposits awaiting confirmation),\n`held` (under compliance review), `available` (spendable) and `locked`\n(reserved by withdrawals in flight). Reading the balance never changes it.","summary":"Current balance, split into its four states","tags":["Balance"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"asset":{"type":"string"},"available":{"type":"string"},"pending":{"type":"string"},"held":{"type":"string"},"locked":{"type":"string"},"total":{"type":"string"}},"required":["asset","available","pending","held","locked","total"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/cards\/config":{"get":{"operationId":"cardConfiguration.show","summary":"Minimal card product catalog for merchant issuer integrations","tags":["Cards"],"responses":{"500":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string","const":"Failed to get card configuration"}},"required":["code","message"]}},"required":["success","error"]}}}},"200":{"description":"Card configuration","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"activation_fee":{"type":"number"},"is_default":{"type":"boolean"},"min_topup_amount":{"type":"number"},"max_topup_amount":{"type":"number"},"kyc_level":{"type":"integer"}},"required":["key","activation_fee","is_default","min_topup_amount","max_topup_amount","kyc_level"]}},"default_product_key":{"type":"string"}},"required":["success","data","default_product_key"]}}}},"503":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"CARD_PRODUCTS_NOT_CONFIGURED"},"message":{"type":"string","const":"No card products are configured"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/cards\/cardholders":{"get":{"operationId":"cardIssuerApi.listCardholders","summary":"List cardholders for the owner","tags":["Cards"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"kyc_status","in":"query","schema":{"type":"string","enum":["0","1","2","3","4"]}},{"name":"requires_approval","in":"query","schema":{"type":"boolean"}},{"name":"search","in":"query","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Paginated list of the owner's cardholders","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"email":{"type":["string","null"]},"requires_approval":{"type":"boolean"},"created_at":{"type":["string","null"]}},"required":["id","first_name","last_name","email","requires_approval","created_at"]}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}},"required":["current_page","last_page","per_page","total"]}},"required":["success","data","meta"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}},"post":{"operationId":"cardIssuerApi.createCardholder","summary":"Create cardholder","tags":["Cards"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Cardholder email address","example":"john.doe@example.com"},"user_name":{"type":"string","description":"Display name","example":"John Doe"},"currency":{"type":"string","description":"Currency for activation fee (USDT or USDC)","example":"USDT"},"product_key":{"type":"string","description":"Card product key from the catalog (catalog slug such as basic, card2, card3, or showcase id). Defaults to the catalog default when omitted.","example":"basic"},"individual":{"type":"object","description":"Individual information","properties":{"first_name":{"type":"string","description":"First name","example":"John"},"last_name":{"type":"string","description":"Last name","example":"Doe"},"date_of_birth":{"type":"string","description":"Date of birth (Y-m-d)","example":"1990-01-15"},"occupation":{"type":"string","description":"Occupation","example":"Engineer"},"annual_income":{"type":"string","description":"Annual income","example":"50000"}},"required":["first_name","last_name","date_of_birth"]},"address":{"type":"object","properties":{"country":{"type":"string","description":"Country ISO 2 code","example":"US"},"city":{"type":"string","description":"City","example":"New York"},"post_code":{"type":"string","description":"Post code","example":"10001"},"details":{"type":"string","description":"Address details","example":"123 Main St"}},"required":["country","city","post_code","details"]},"document":{"type":"object","properties":{"type":{"type":"string","description":"Document type: 1=National ID, 2=Passport","example":"2"},"number":{"type":"string","description":"Document number","example":"AB1234567"},"front":{"type":"string","description":"Front side of the document (the page with the holder's photo), Base64-encoded as a data URI: `data:image\/jpeg;base64,...` or `data:image\/png;base64,...`. JPEG or PNG only; shorter image edge \u2265300 px; decoded payload \u22655000 bytes and <3MB.","example":"data:image\/jpeg;base64,\/9j\/4AAQSkZJRg..."},"back":{"type":"string","description":"Optional. Back side of the document (e.g. national ID), same format and quality rules as `document.front` (<3MB decoded).","example":"data:image\/jpeg;base64,\/9j\/4AAQSkZJRg..."},"face":{"type":"string","description":"Optional selfie \/ face image for additional verification. Same data URI format and image quality rules as `document.front` (<3MB decoded).","example":"data:image\/jpeg;base64,\/9j\/4AAQSkZJRg..."},"country":{"type":"string","description":"Document issuing country (ISO 2)","example":"US"},"expiry_date":{"type":"string","description":"Document expiry date (Y-m-d)","example":"2030-12-31"}}}},"required":["email","individual","address"]}}}},"responses":{"200":{"description":"Cardholder created","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"},"requires_approval":{"type":"boolean"}},"required":["id","status","requires_approval"]}},"required":["success","message","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"400":{"description":"Bad request","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INSUFFICIENT_BALANCE"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]},{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"WALLET_ERROR"},"message":{"type":"string","const":"Currency not supported or wallet not found"}},"required":["code","message"]}},"required":["success","error"]},{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]},{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"PRODUCT_DISABLED"},"message":{"type":"string","const":"This card product is coming soon and cannot be ordered yet."}},"required":["code","message"]}},"required":["success","error"]},{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INVALID_PRODUCT"},"message":{"type":"string","const":"Card product is not configured or invalid"}},"required":["code","message"]}},"required":["success","error"]},{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}]}}}},"404":{"$ref":"#\/components\/responses\/NotFoundHttpException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/cards\/cardholders\/{id}\/upload-kyc":{"post":{"operationId":"cardIssuerApi.uploadCardholderKyc","description":"Use when the cardholder was created with partial documents (e.g. front only) to add back, selfie, or refresh all fields.","summary":"Upload or upgrade KYC documents for an existing cardholder","tags":["Cards"],"parameters":[{"name":"id","in":"path","required":true,"description":"Cardholder ID (integer)","schema":{"type":"integer"},"example":42}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"individual":{"type":"object","properties":{"first_name":{"type":"string","description":"First name","example":"John"},"last_name":{"type":"string","description":"Last name","example":"Doe"},"date_of_birth":{"type":"string","description":"Date of birth (Y-m-d)","example":"1990-01-15"},"occupation":{"type":"string","description":"Occupation","example":"Engineer"},"annual_income":{"type":"string","description":"Annual income","example":"50000"}},"required":["first_name","last_name","date_of_birth"]},"address":{"type":"object","properties":{"country":{"type":"string","description":"Country ISO 2 code","example":"US"},"city":{"type":"string","description":"City","example":"New York"},"post_code":{"type":"string","description":"Post code","example":"10001"},"details":{"type":"string","description":"Address details","example":"123 Main St"}},"required":["country","city","post_code","details"]},"document":{"type":"object","properties":{"type":{"type":"string","description":"Document type: 1=National ID, 2=Passport","example":"2"},"number":{"type":"string","description":"Document number","example":"AB1234567"},"front":{"type":"string","description":"Front side of the document, Base64 data URI (JPEG\/PNG, \u2265300 px short edge, \u22655000 bytes, <3MB decoded).","example":"data:image\/jpeg;base64,\/9j\/4AAQSkZJRg..."},"back":{"type":"string","description":"Optional back side of the document, same format as front.","example":"data:image\/jpeg;base64,\/9j\/4AAQSkZJRg..."},"face":{"type":"string","description":"Optional selfie for additional verification, same format as front.","example":"data:image\/jpeg;base64,\/9j\/4AAQSkZJRg..."},"country":{"type":"string","description":"Document issuing country (ISO 2)","example":"US"},"expiry_date":{"type":"string","description":"Document expiry date (Y-m-d)","example":"2030-12-31"}},"required":["type","number","front","country","expiry_date"]}},"required":["id","individual","address","document"]}}}},"responses":{"200":{"description":"KYC documents uploaded","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"integer"},"kyc_status":{"type":["string","null"]}},"required":["id","kyc_status"]}},"required":["success","message","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Cardholder not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/cards\/cardholders\/{id}\/cards":{"get":{"operationId":"cardIssuerApi.listCardholderCards","summary":"List cards of a cardholder","tags":["Cards"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","INACTIVE","LOCKED","SUSPENDED","CLOSED","PENDING"]}},{"name":"card_type","in":"query","schema":{"type":"string","enum":["virtual","physical"]}},{"name":"currency","in":"query","schema":{"type":"string","maxLength":10}},{"name":"card_level","in":"query","schema":{"type":"string","maxLength":10}},{"name":"id","in":"path","required":true,"description":"Cardholder ID (integer)","schema":{"type":"integer"},"example":42}],"responses":{"200":{"description":"Paginated list of cardholder cards","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"card_id":{"type":["string","null"]},"type":{"type":"string"},"status":{"type":"string"},"balance":{"type":"number"},"currency":{"type":["string","null"]},"last_four":{"type":"string"}},"required":["id","card_id","type","status","balance","currency","last_four"]}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}},"required":["current_page","last_page","per_page","total"]}},"required":["success","data","meta"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Cardholder not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards\/cardholders\/{id}":{"get":{"operationId":"cardIssuerApi.showCardholder","summary":"Show one cardholder","tags":["Cards"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"id","in":"path","required":true,"description":"Cardholder ID (integer)","schema":{"type":"integer"},"example":42}],"responses":{"200":{"description":"Cardholder details","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"integer"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"email":{"type":["string","null"]},"requires_approval":{"type":"boolean"},"created_at":{"type":["string","null"]}},"required":["id","first_name","last_name","email","requires_approval","created_at"]}},"required":["success","data"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Cardholder not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards\/cardholders\/{id}\/apply":{"post":{"operationId":"cardIssuerApi.applyCard","summary":"Issue card for a cardholder","tags":["Cards"],"parameters":[{"name":"id","in":"path","required":true,"description":"Cardholder ID (integer)","schema":{"type":"integer"},"example":42}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"phone_number":{"type":"string","description":"Phone number (digits only, 6-20 chars)","example":"5551234567"},"phone_area_code":{"type":"string","description":"Phone area\/country code (e.g. 1 for US)","example":"1"},"embossed_name":{"type":"string","description":"Name to emboss on the card","example":"JOHN DOE"},"currency":{"type":"string","description":"Currency for card fee","example":"USDT"},"product_key":{"type":"string","description":"Card product key from the catalog (catalog slug or showcase id). Defaults to the catalog default when omitted.","example":"basic"}},"required":["id","phone_number","phone_area_code","embossed_name"]}}}},"responses":{"200":{"description":"Card application created","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"card_id":{"type":["string","null"]},"request_id":{"type":"string"},"status":{"type":["string","null"]}},"required":["card_id","request_id","status"]}},"required":["success","data"]}}}},"400":{"description":"Bad request","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}}}},"404":{"$ref":"#\/components\/responses\/NotFoundHttpException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards":{"get":{"operationId":"cardIssuerApi.listCards","summary":"List cards for the owner","tags":["Cards"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","INACTIVE","LOCKED","SUSPENDED","CLOSED","PENDING"]}},{"name":"card_type","in":"query","schema":{"type":"string","enum":["virtual","physical"]}},{"name":"currency","in":"query","schema":{"type":"string","maxLength":10}},{"name":"card_level","in":"query","schema":{"type":"string","maxLength":10}}],"responses":{"200":{"description":"Paginated list of all cards","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"card_id":{"type":["string","null"]},"type":{"type":"string"},"status":{"type":"string"},"balance":{"type":"number"},"currency":{"type":["string","null"]},"last_four":{"type":"string"}},"required":["id","card_id","type","status","balance","currency","last_four"]}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}},"required":["current_page","last_page","per_page","total"]}},"required":["success","data","meta"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards\/{id}":{"get":{"operationId":"cardIssuerApi.showCard","summary":"Show one card","tags":["Cards"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"id","in":"path","required":true,"description":"Card ID (integer)","schema":{"type":"integer"},"example":7}],"responses":{"200":{"description":"Card details","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"integer"},"card_id":{"type":["string","null"]},"type":{"type":"string"},"card_type":{"type":["string","null"]},"card_number":{"type":["string","null"]},"status":{"type":"string"},"balance":{"type":"number"},"currency":{"type":["string","null"]},"frozen_balance":{"type":"number"},"available_balance":{"type":"number"},"daily_limit":{"type":"number"},"daily_spent":{"type":"number"},"last_four":{"type":"string"},"embossed_name":{"type":["string","null"]},"created_at":{"type":["string","null"]},"expiry_month":{"type":["string","null"]},"expiry_year":{"type":["string","null"]},"card_network":{"type":["string","null"]}},"required":["id","card_id","type","card_type","card_number","status","balance","currency","frozen_balance","available_balance","daily_limit","daily_spent","last_four","embossed_name","created_at","expiry_month","expiry_year","card_network"]}},"required":["success","data"]}}}},"502":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string","const":"Something went wrong. Please try again later."}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Card not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards\/{id}\/topup":{"post":{"operationId":"cardIssuerApi.topUpCard","summary":"Top up a card","tags":["Cards"],"parameters":[{"name":"id","in":"path","required":true,"description":"Card ID (integer)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"amount":{"type":"string","description":"Top-up amount","example":"100.00"},"currency":{"type":"string","description":"Currency (USDT or USDC)","example":"USDT"}},"required":["id","amount"]}}}},"responses":{"500":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string","const":"Something went wrong. Please try again later."}},"required":["code","message"]}},"required":["success","error"]}}}},"200":{"description":"Top-up initiated","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"card_id":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string"}},"required":["card_id","amount","currency","status"]}},"required":["success","message","data"]}}}},"400":{"description":"Bad request","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"CARDHOLDER_PENDING_APPROVAL"},"message":{"type":"string","const":"Cardholder requires manual approval. Please wait for approval."}},"required":["code","message"]}},"required":["success","error"]},{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}]}}}},"404":{"$ref":"#\/components\/responses\/NotFoundHttpException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"},"403":{"$ref":"#\/components\/responses\/AuthorizationException"}}}},"\/cards\/{id}\/activate":{"post":{"operationId":"cardIssuerApi.activateCard","summary":"Activate a card","tags":["Cards"],"parameters":[{"name":"id","in":"path","required":true,"description":"Card ID (integer)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","minimum":1}},"required":["id"]}}}},"responses":{"400":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string","const":"Something went wrong. Please try again later."}},"required":["code","message"]}},"required":["success","error"]},{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"CARD_NOT_READY"},"message":{"type":"string","const":"Card is still initializing. Refresh status and try again."}},"required":["code","message"]}},"required":["success","error"]}]}}}},"200":{"description":"Card activated","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["success","data"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Card not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards\/{id}\/lock":{"post":{"operationId":"cardIssuerApi.lockCard","summary":"Lock a card","tags":["Cards"],"parameters":[{"name":"id","in":"path","required":true,"description":"Card ID (integer)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LockCardRequest"}}}},"responses":{"400":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string","const":"Something went wrong. Please try again later."}},"required":["code","message"]}},"required":["success","error"]}}}},"200":{"description":"Card locked","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"integer"},"card_id":{"type":["string","null"]},"type":{"type":"string"},"status":{"type":"string"},"balance":{"type":"number"},"currency":{"type":["string","null"]},"last_four":{"type":"string"}},"required":["id","card_id","type","status","balance","currency","last_four"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Card not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/cards\/{id}\/unlock":{"post":{"operationId":"cardIssuerApi.unlockCard","summary":"Unlock a card","tags":["Cards"],"parameters":[{"name":"id","in":"path","required":true,"description":"Card ID (integer)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/UnlockCardRequest"}}}},"responses":{"400":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string","const":"Something went wrong. Please try again later."}},"required":["code","message"]}},"required":["success","error"]}}}},"200":{"description":"Card unlocked","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"integer"},"card_id":{"type":["string","null"]},"type":{"type":"string"},"status":{"type":"string"},"balance":{"type":"number"},"currency":{"type":["string","null"]},"last_four":{"type":"string"}},"required":["id","card_id","type","status","balance","currency","last_four"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Card not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/cards\/{id}\/transactions":{"get":{"operationId":"cardIssuerApi.getCardTransactions","description":"Returns top-ups, purchases, and fees for one card, newest first.\n\n## A purchase is reported twice \u2014 do not sum `status`\n\nA card purchase goes through two stages:\n\n1. **Authorization.** The moment the cardholder pays, the issuer places a hold. The card\n   balance is **already** reduced by it, even though the card itself reports\n   `frozen_balance: 0` and `daily_spent: 0`. Hold rows (`settlement_state: \"authorized\"`)\n   appear in this list only when you pass `include_authorizations=true` \u2014 without it your\n   row set stays exactly as before this field existed, but the card balance will disagree\n   with the visible rows while holds are outstanding.\n2. **Settlement.** When the merchant clears the payment \u2014 typically hours later, up to three\n   business days \u2014 the issuer creates a **new row** with a **new** `provider_reference` and\n   `settlement_state: \"settled\"`, and flips the original hold to `settlement_state:\n   \"released\"`. **Both settlement-stage rows are always in the list**, with or without the\n   flag \u2014 that has always been the case.\n\nSo a settled purchase is present as two rows. Adding both would double-count it; ignoring\nthe authorization phase makes your ledger disagree with the card balance for hours. Use\n`affects_balance` and `settlement_group` instead of the raw `status` string, which is the\nissuer's vocabulary and is not stable (a released hold arrives spelled `CANCELLED`, while\nother issuer surfaces spell the same state `CANCELED`).\n\n## Reconciling the balance\n\nSum one field, `balance_impact` \u2014 a signed amount in the CARD's currency (`balance_currency`),\npositive for credits and negative for debits, and already zero on every row that does not\ncount:\n\n```text\ncard balance = \u03a3 balance_impact\n```\n\nDo **not** sum `formatted_amount` on a purchase: it is denominated in the merchant's currency\n(`240.00 GBP`), while the card was debited `335.7768 USDT`. `affects_balance` tells you why a\nrow counts \u2014 true for `authorized` and `settled`, plus top-ups the provider has already\ncredited; false for `released`, `declined` and `pending_funding`.\n\nWith `include_authorizations=true`, the sum matches the card balance **at any moment**.\nWithout the flag it converges only once every purchase has settled \u2014 enable the flag if you\nreconcile in real time. Worked example from production, a card credited with 2 \u00d7 1 000 USDT\nthat then made five purchases and paid four cross-border fees:\n\n```text\ntop-ups            +2000.0000 (2 rows, settled)\nsettled purchases  -1051.3302 (5 rows, settled)\nsettled fees          -0.8124 (4 rows, settled)\nreleased holds         0.0000 (5 rows, released \u2014 balance_impact is 0)\n= balance            947.8574\n```\n\nBefore those purchases settled, the same balance came out of the authorizations\n(`2000 \u2212 0.8124 \u2212 1051.3303`) \u2014 that is the point: the sum is stable across settlement, so you\ncan run it at any moment, and it will agree with the card.\n\n## Displaying a statement\n\nPass `collapse_settlements=true` and each payment is returned as **one row**: the released\nhalf of every settled purchase is dropped server-side, so the page you receive is already\nthe statement and `meta.total` counts real payments.\n\nDo not attempt this grouping yourself. The two rows of a pair are created hours apart, so\nordered by date they land on **different pages** \u2014 client-side grouping leaves orphaned\n\"released\" lines behind whenever a pair straddles a page boundary. And do not pair rows by\nmerchant name or amount: the issuer rewrites the merchant name at settlement\n(\"EXAMPLE STORE MALAGA ESP\" becomes \"EXAMPLE STORE\") and may round the settled amount differently in\nthe last decimal.\n\n`settlement_group` is provided so you can still recognise a pair when you deliberately keep\nboth rows (`collapse_settlements` off, e.g. for an audit view): both members carry the same\nkey, and a row still awaiting settlement has `settlement_group: null`.\n\nTo flag an outstanding hold in a UI, read the boolean `is_authorization_hold` rather than\ncomparing `settlement_state` to a literal \u2014 the boolean is part of the contract, the enum's\nspelling is free to grow.\n\n`authorization_amount` \/ `authorization_currency` carry the original merchant-currency figure\n(e.g. 240.00 GBP behind a 335.78 USDT charge) \u2014 that is what the cardholder recognises from\nthe receipt. Zero-amount `authorized` rows are merchant validity probes: they never settle and\nnever move money.\n\n## Which status field to build on\n\n`settlement_state` is the **stable, versioned vocabulary** of this API \u2014 exactly five values\n(`authorized`, `settled`, `released`, `declined`, `pending_funding`), guaranteed across\nreleases and across any change of the underlying card issuer. Build all logic on it, together\nwith `affects_balance` and `balance_impact`.\n\n`status` is the card issuer's **native value, passed through verbatim** for transparency and\nsupport conversations. Its vocabulary is not ours to promise: values may be added, renamed or\nspelled inconsistently by the issuer (the same released hold arrives as `CANCELLED` where\nother issuer surfaces say `CANCELED`), and the whole set changes if the issuing partner\nchanges. Do not switch on it, do not sum by it, do not treat an unknown value as an error.\n\n`settlement_group` and `provider_reference` are **opaque tokens**: compare `settlement_group`\nfor equality within one response to pair rows, quote `provider_reference` to support \u2014 never\nparse either, their internal format may change without notice.","summary":"List transactions for a card","tags":["Cards"],"parameters":[{"name":"page","in":"query","description":"cardId comes from route parameter, validated in controller","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"id","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"include_authorizations","in":"query","description":"Opt-in: also list open authorization holds (settlement_state \"authorized\").\nOff by default so pre-existing integrations keep their row set unchanged.","schema":{"type":"boolean"}},{"name":"collapse_settlements","in":"query","description":"Opt-in: drop the released half of a settled purchase, so each payment is one row.","schema":{"type":"boolean"}},{"name":"id","in":"path","required":true,"description":"Card ID (integer)","schema":{"type":"integer"},"example":7}],"responses":{"200":{"description":"Paginated card transactions, newest first. A settled purchase appears TWICE (the released authorization and the settled row that replaced it) \u2014 sum only rows with affects_balance = true, and group by settlement_group for display. settlement_state is one of authorized|settled|released|declined|pending_funding. Reconcile the balance by summing balance_impact (signed, in balance_currency) \u2014 never formatted_amount, which is denominated in the merchant currency on purchases. settlement_state is the stable vocabulary; the raw status field is the card issuer native value passed through verbatim and may change with the issuing partner \u2014 do not build logic on it. settlement_group and provider_reference are opaque tokens: compare for equality, never parse. Raw money fields are non-null only on top-up rows; credited_amount\/provider_fee\/settled_at stay null until the provider webhook settles the row (status SUCCESS alone does not mean credited).","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"symbol":{"type":"string"},"timestamp":{"type":"string"},"formatted_amount":{"type":"string"},"formatted_order_amount":{"type":"string"},"status":{"type":"string"},"settlement_state":{"type":"string"},"is_authorization_hold":{"type":"boolean"},"affects_balance":{"type":"boolean"},"balance_impact":{"type":"number"},"balance_currency":{"type":["string","null"]},"settlement_group":{"type":["string","null"]},"authorization_amount":{"type":["number","null"]},"authorization_currency":{"type":["string","null"]},"provider_reference":{"type":["string","null"]},"authorized_at":{"type":["string","null"]},"posted_at":{"type":["string","null"]},"paid_amount":{"type":["number","null"]},"paid_currency":{"type":["string","null"]},"platform_fee":{"type":["number","null"]},"provider_fee":{"type":["number","null"]},"provider_fee_currency":{"type":["string","null"]},"credited_amount":{"type":["number","null"]},"credited_currency":{"type":["string","null"]},"settled_at":{"type":["string","null"]}},"required":["id","type","symbol","timestamp","formatted_amount","formatted_order_amount","status","settlement_state","is_authorization_hold","affects_balance","balance_impact","balance_currency","settlement_group","authorization_amount","authorization_currency","provider_reference","authorized_at","posted_at","paid_amount","paid_currency","platform_fee","provider_fee","provider_fee_currency","credited_amount","credited_currency","settled_at"]}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}},"required":["current_page","last_page","per_page","total"]}},"required":["success","data","meta"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Card not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards\/{id}\/spending-summary":{"get":{"operationId":"cardIssuerApi.getCardSpendingSummary","summary":"Spending summary for a card (daily limit, current spending)","tags":["Cards"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"id","in":"path","required":true,"description":"Card ID (integer)","schema":{"type":"integer"},"example":7}],"responses":{"200":{"description":"Card spending summary","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"current":{"type":"number"},"daily_purchase_limit":{"type":"string"}},"required":["current","daily_purchase_limit"]}},"required":["success","data"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Card not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards\/{id}\/sensitive-info":{"post":{"operationId":"cardIssuerApi.getCardSensitiveInfo","summary":"Get short-lived sensitive card data (PAN, expiry, CVV)","tags":["Cards"],"parameters":[{"name":"id","in":"path","required":true,"description":"Card ID (integer)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","minimum":1}},"required":["id"]}}}},"responses":{"502":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string","const":"Something went wrong. Please try again later."}},"required":["code","message"]}},"required":["success","error"]}}}},"200":{"description":"Sensitive card data (short-lived)","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"card_id":{"type":["string","null"]},"card_number":{"type":["string","null"]},"expiry_month":{"type":["string","null"]},"expiry_year":{"type":["string","null"]},"security_code":{"type":["string","null"]},"expires_at":{"type":["string","null"]}},"required":["card_id","card_number","expiry_month","expiry_year","security_code","expires_at"]}},"required":["success","data"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Card not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards\/{id}\/info":{"post":{"operationId":"cardIssuerApi.refreshCardInfo","summary":"Refresh card info (balance, status, etc.)","tags":["Cards"],"parameters":[{"name":"id","in":"path","required":true,"description":"Card ID (integer)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","minimum":1}},"required":["id"]}}}},"responses":{"502":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string","const":"Something went wrong. Please try again later."}},"required":["code","message"]}},"required":["success","error"]}}}},"200":{"description":"Card info refreshed","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"string"},"status_label":{"type":"string"},"card_id":{"type":["string","null"]},"can_activate":{"type":"boolean"},"can_unlock":{"type":"boolean"}},"required":["message","status","status_label","card_id","can_activate","can_unlock"]}},"required":["success","data"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Card not found"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/cards\/audit-status":{"post":{"operationId":"cardIssuerApi.checkAuditStatus","summary":"Check card application (audit) status by request_id","tags":["Cards"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","description":"The card application request ID","example":"extra_card_550e8400-e29b-41d4-a716-446655440000"}},"required":["request_id"]}}}},"responses":{"500":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"INTERNAL_ERROR"},"message":{"type":"string","const":"Something went wrong. Please try again later."}},"required":["code","message"]}},"required":["success","error"]}}}},"200":{"description":"Audit status retrieved","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"request_id":{"type":"string"},"status":{"type":"string"},"message":{"type":"string"}},"required":["request_id","status","message"]}},"required":["success","data"]}}}},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"NOT_FOUND"},"message":{"type":"string","const":"Application not found for this request_id"}},"required":["code","message"]}},"required":["success","error"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/api\/bridge\/cases":{"get":{"operationId":"bridge.cases.index","summary":"The user's support\/AML cases","tags":["Case"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"cases":{"type":"array","items":{}}},"required":["cases"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"post":{"operationId":"bridge.cases.store","summary":"Open a new support case (SPEC \u00a717","tags":["Case"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StoreCaseRequest"}}}},"responses":{"201":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"case":{"type":"array","items":{}}},"required":["case"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}},"description":"Open a new support case (SPEC \u00a717 \u2014 simple case workflow)"}},"\/api\/bridge\/cases\/{case}":{"get":{"operationId":"bridge.cases.show","summary":"A case with its message thread","tags":["Case"],"parameters":[{"name":"case","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"case":{"type":"array","items":{}}},"required":["case"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/cases\/{case}\/messages":{"post":{"operationId":"bridge.cases.messages","summary":"Add a user message to an existing case (re-opens a resolved one)","tags":["Case"],"parameters":[{"name":"case","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StoreCaseMessageRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"case":{"type":"array","items":{}}},"required":["case"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/currencies":{"get":{"operationId":"listCurrencies","description":"Retrieves all available currencies on the platform.\nIncludes both cryptocurrencies and fiat currencies with their details.","summary":"List All Currencies","tags":["Currencies"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}}}}},"\/api\/bridge\/deposits":{"get":{"operationId":"bridge.deposits.index","summary":"Paginated deposit history with ledger-derived timelines","tags":["Deposit"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"deposits":{"type":"array","items":{}},"has_more":{"type":"boolean"},"page":{"type":"integer"}},"required":["deposits","has_more","page"]}},"required":["success","data"]},{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"deposits":{"type":"array","items":{"type":"string"},"minItems":0,"maxItems":0,"additionalItems":false},"has_more":{"type":"boolean"}},"required":["deposits","has_more"]}},"required":["success","data"]}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/deposit\/addresses":{"get":{"operationId":"bridge.deposits.addresses","summary":"Permanent deposit addresses per supported network (SPEC \u00a77).","tags":["Deposit"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"asset":{"type":"string"},"networks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"payment_id":{"type":["string","null"]},"available":{"type":"boolean"},"min_deposit":{"type":"string"},"confirmations_required":{"type":"integer"}},"required":["id","slug","name","address","payment_id","available","min_deposit","confirmations_required"]}}},"required":["asset","networks"]}},"required":["success","data"]}}}},"503":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"ASSET_NOT_CONFIGURED"},"message":{"type":"string","const":"Deposits are temporarily unavailable."}},"required":["code","message"]}},"required":["success","error"]},{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"DEPOSITS_DISABLED"},"message":{"type":"string","const":"Deposits are temporarily unavailable."}},"required":["code","message"]}},"required":["success","error"]}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"description":"Permanent deposit addresses per supported network (SPEC \u00a77).\nAddresses are generated lazily on first request and reused afterwards"}},"\/orders\/futures\/cancel":{"post":{"operationId":"cancelFuturesOrder","description":"Cancels a pending futures limit order or closes an active futures position.\nFor pending orders, the locked margin will be returned.\nFor active positions, the position will be closed at market price and PNL settled.","summary":"Close Futures Position","tags":["Futures Trading"],"requestBody":{"content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/OrderFuturesCancelRequest"},{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"The UUID of the order\/position to cancel\/close","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["uuid"]}]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"message":{"type":"string","enum":["request processed","request_was_not_processed"]}},"required":["message"]},{"type":"string"}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/orders\/futures\/open":{"get":{"operationId":"getOpenFuturesPositions","description":"Retrieves all open (active) futures positions for the authenticated user.\nIncludes position details such as entry price, liquidation price, unrealized PNL, etc.","summary":"Get Open Futures Positions","tags":["Futures Trading"],"parameters":[{"name":"market","in":"query","description":"Filter by market pair name","schema":{"type":"string"},"example":"BTC-USDT"}],"responses":{"200":{"description":"`OpenFuturesOrderCollection`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/OpenFuturesOrderCollection"},"success":{"type":"boolean"}},"required":["data","success"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/orders\/futures\/orders":{"get":{"operationId":"getPendingFuturesOrders","description":"Retrieves all pending (unfilled) futures limit orders for the authenticated user.\nThese are orders that have been placed but not yet executed.","summary":"Get Pending Futures Orders","tags":["Futures Trading"],"parameters":[{"name":"market","in":"query","description":"Filter by market pair name","schema":{"type":"string"},"example":"BTC-USDT"}],"responses":{"200":{"description":"`OpenFuturesOrderCollection`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/OpenFuturesOrderCollection"},"success":{"type":"boolean"}},"required":["data","success"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/me":{"get":{"operationId":"bridge.me","summary":"Current user profile with linked sign-in methods","tags":["Identity"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"user":{"type":"array","items":{}}},"required":["user"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/auth\/link\/telegram":{"post":{"operationId":"bridge.auth.link.telegram","summary":"Link a Telegram identity to the current account.","tags":["Identity"],"requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LinkTelegramRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"user":{"type":"array","items":{}}},"required":["user"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"description":"Link a Telegram identity to the current account.\nRequires TOTP when enabled (SPEC \u00a74)"}},"\/api\/bridge\/auth\/link\/google":{"post":{"operationId":"bridge.auth.link.google","summary":"Link a Google identity to the current account.","tags":["Identity"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LinkGoogleRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"user":{"type":"array","items":{}}},"required":["user"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"description":"Link a Google identity to the current account.\nRequires TOTP when enabled (SPEC \u00a74)"}},"\/api\/bridge\/auth\/link\/email\/request-otp":{"post":{"operationId":"bridge.auth.link.email.request","summary":"Send a verification code to a new email address for linking","tags":["Identity"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RequestLinkEmailOtpRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string","const":"We sent a verification code to your email."},"resend_in":{"type":"integer"}},"required":["message","resend_in"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/auth\/link\/email\/verify":{"post":{"operationId":"bridge.auth.link.email.verify","summary":"Confirm email linking with the emailed code.","tags":["Identity"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ConfirmLinkEmailRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"user":{"type":"array","items":{}}},"required":["user"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"description":"Confirm email linking with the emailed code.\nRequires TOTP when enabled (email is a critical profile attribute)"}},"\/api\/bridge\/kyb":{"get":{"operationId":"bridge.kyb.show","summary":"Current KYB state: virtual 'not_started' until the first write creates","tags":["Kyb"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"string","enum":["not_started"]}]},"company":{"type":["array","null"],"items":{}},"documents":{"type":"array","items":{}},"info_request":{"type":"string"},"rejection_reason":{"type":"string"},"can_edit":{"type":"boolean"},"document_types":{"type":"array","items":{}}},"required":["status","company","documents","info_request","rejection_reason","can_edit","document_types"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"description":"Current KYB state: virtual 'not_started' until the first write creates\nthe draft row"}},"\/api\/bridge\/kyb\/submit":{"post":{"operationId":"bridge.kyb.submit","summary":"Submit the questionnaire for compliance review","tags":["Kyb"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"string","enum":["not_started"]}]},"company":{"type":["array","null"],"items":{}},"documents":{"type":"array","items":{}},"info_request":{"type":"string"},"rejection_reason":{"type":"string"},"can_edit":{"type":"boolean"},"document_types":{"type":"array","items":{}}},"required":["status","company","documents","info_request","rejection_reason","can_edit","document_types"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/kyb\/documents":{"post":{"operationId":"bridge.kyb.documents.store","summary":"Upload a verification document","tags":["Kyb"],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"$ref":"#\/components\/schemas\/UploadKybDocumentRequest"}}}},"responses":{"201":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"document":{"type":"array","items":{}},"status":{"anyOf":[{"type":"string"},{"type":"string","enum":["not_started"]}]},"company":{"type":["array","null"],"items":{}},"documents":{"type":"array","items":{}},"info_request":{"type":"string"},"rejection_reason":{"type":"string"},"can_edit":{"type":"boolean"},"document_types":{"type":"array","items":{}}},"required":["document","status","company","documents","info_request","rejection_reason","can_edit","document_types"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/kyb\/documents\/{document}\/download":{"get":{"operationId":"bridge.kyb.documents.download","summary":"Stream a document back to its owner","tags":["Kyb"],"parameters":[{"name":"document","in":"path","required":true,"description":"The document ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object"}}}},"403":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"FORBIDDEN"},"message":{"type":"string","const":"You do not have access to this document."}},"required":["code","message"]}},"required":["success","error"]}}}},"404":{"$ref":"#\/components\/responses\/ModelNotFoundException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/launchpads":{"get":{"operationId":"listLaunchpadProjects","description":"Retrieves all launchpad\/IEO (Initial Exchange Offering) projects.\nStatus options: all, upcoming, active, ended","summary":"List Launchpad Projects","tags":["Launchpad"],"parameters":[{"name":"sort","in":"path","required":true,"description":"Filter by status: all, upcoming, active, ended","schema":{"type":"string"},"example":"active"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"launchpads":{"$ref":"#\/components\/schemas\/LaunchpadCollection"},"sort":{"type":"string"}},"required":["launchpads","sort"]}}}}}}},"\/launchpad":{"get":{"operationId":"getLaunchpadProjectDetails","description":"Retrieves detailed information about a specific launchpad project.","summary":"Get Launchpad Project Details","tags":["Launchpad"],"parameters":[{"name":"id","in":"query","required":true,"description":"The launchpad project ID","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"launchpad":{"$ref":"#\/components\/schemas\/Launchpad"}},"required":["launchpad"]},{"type":"string"}]}}}}}}},"\/launchpad\/submit":{"post":{"operationId":"launchpads.api.submit","tags":["Launchpad"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LaunchpadPurchaseRequest"}}}},"responses":{"500":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"Purchase failed. Please try again."}},"required":["success","message"]}}}},"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"Launchpad not found"}},"required":["success","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/market\/info":{"get":{"operationId":"getMarketInfo","description":"Retrieves detailed information about a specific market pair.\nIncludes trading rules, precision settings, and fee information.","summary":"Get Market Info","tags":["Market Data"],"parameters":[{"name":"market","in":"query","required":true,"description":"The market pair name","schema":{"type":"string"},"example":"BTC-USDT"}],"responses":{"200":{"description":"`Market`","content":{"application\/json":{"schema":{"anyOf":[{"$ref":"#\/components\/schemas\/Market"},{"type":"object","properties":{"result":{"type":"boolean"},"message":{"type":"string","const":"Wrong market name"}},"required":["result","message"]}]}}}}}}},"\/markets\/swap\/info":{"get":{"operationId":"getSwapConfig","description":"Retrieves configuration data for the instant swap\/exchange feature.\nReturns available currencies and default trading pair for quick swaps.","summary":"Get Swap Configuration","tags":["Market Data"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}}}}},"\/markets\/ticker":{"get":{"operationId":"getMarketTicker","description":"Retrieves 24-hour price statistics for one or all trading pairs.\nIf market parameter is provided, returns data for that specific pair.\nOtherwise, returns data for all active markets.\n\n**Ticker Data Includes:** Last price, bid\/ask prices, 24h high\/low\/volume, price change","summary":"Get Market Ticker","tags":["Market Data"],"parameters":[{"name":"market","in":"query","description":"Specific market pair name. If omitted, returns all markets","schema":{"type":"string"},"example":"BTC-USDT"}],"responses":{"200":{"description":"`MarketCollection`\n\n`Market`","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/MarketCollection"},"success":{"type":"boolean"}},"required":["data","success"]},{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Market"}},"required":["data"]}]}}}}}}},"\/markets\/trades":{"get":{"operationId":"getRecentTrades","description":"Retrieves the most recent trades for a specific market.\nReturns trades in reverse chronological order (newest first).","summary":"Get Recent Trades","tags":["Market Data"],"parameters":[{"name":"market","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`TransactionCollection`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/TransactionCollection"},"success":{"type":"boolean"}},"required":["data","success"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/markets\/candles\/{query}":{"get":{"operationId":"getOHLCVCandles","description":"Retrieves candlestick (OHLCV) data for charting.\nSupported intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w","summary":"Get OHLCV Candles","tags":["Market Data"],"parameters":[{"name":"query","in":"path","required":true,"description":"**Optional**","schema":{"type":"string"},"x-optional":true},{"name":"market","in":"query","required":true,"schema":{"type":"string"}},{"name":"interval","in":"query","description":"Candlestick interval (1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w)","schema":{"type":"string"},"example":"1h"},{"name":"limit","in":"query","description":"Number of candles to return","schema":{"type":"integer"},"example":100}],"responses":{"200":{"description":"`CandleCollection`","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CandleCollection"}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/markets\/orderbook":{"get":{"operationId":"getOrderBook","description":"Retrieves the current order book (bids and asks) for a specific market.\nOrders are aggregated by price level and sorted by price.","summary":"Get Order Book","tags":["Market Data"],"parameters":[{"name":"market","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"bids":{"type":"array","items":{"type":"object","properties":{"price":{"type":"string"},"quantity":{}},"required":["price","quantity"]}},"asks":{"type":"array","items":{"type":"object","properties":{"price":{"type":"string"},"quantity":{}},"required":["price","quantity"]}}},"required":["bids","asks"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/markets\/historical\/trades":{"get":{"operationId":"getHistoricalTrades","description":"Retrieves historical trades from liquidity provider for markets with liquidity bridging.\nReturns the most recent trades from external liquidity sources.","summary":"Get Historical Trades","tags":["Market Data"],"parameters":[{"name":"market","in":"query","required":true,"description":"The market pair name","schema":{"type":"string"},"example":"BTC-USDT"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"trades":{"type":"array","items":{"type":"string"},"minItems":0,"maxItems":0,"additionalItems":false},"success":{"type":"boolean"}},"required":["trades","success"]},{"type":"object","properties":{"trades":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"price":{"type":"string"},"quantity":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]}},"required":["created_at","price","quantity","side"]}},"success":{"type":"boolean"}},"required":["trades","success"]},{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}]}}}}}}},"\/spot\/markets":{"get":{"operationId":"marketCmc.markets","summary":"Display a listing of the markets","tags":["Market Data"],"responses":{"200":{"description":"Array of `MarketCmc`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/MarketCmc"}}},"required":["data"]}}}}}}},"\/spot\/ticker":{"get":{"operationId":"marketCmc.ticker","summary":"Display a listing of the ticker per each market","tags":["Market Data"],"responses":{"200":{"description":"Array of `TickerCmc`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/TickerCmc"}}},"required":["data"]}}}}}}},"\/spot\/orderbook":{"get":{"operationId":"marketCmc.orderbook","summary":"Display a listing of bids\/asks per marker orderbook","tags":["Market Data"],"parameters":[{"name":"market_pair","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/spot\/trades":{"get":{"operationId":"marketCmc.trades","tags":["Market Data"],"parameters":[{"name":"market_pair","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Array of `TransactionCmc`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/TransactionCmc"}}},"required":["data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/spot\/assets":{"get":{"operationId":"marketCmc.assets","summary":"Display a listing of market assets","tags":["Market Data"],"responses":{"200":{"description":"Array of `AssetCmc`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/AssetCmc"}}},"required":["data"]}}}}}}},"\/spot\/cg\/pairs":{"get":{"operationId":"marketCoingecko.pairs","tags":["Market Data"],"responses":{"200":{"description":"Array of `PairCoingecko`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/PairCoingecko"}}},"required":["data"]}}}}}}},"\/spot\/cg\/tickers":{"get":{"operationId":"marketCoingecko.tickers","tags":["Market Data"],"responses":{"200":{"description":"Array of `TickerCoingecko`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/TickerCoingecko"}}},"required":["data"]}}}}}}},"\/spot\/cg\/orderbook":{"get":{"operationId":"marketCoingecko.orderbook","summary":"Display a listing of bids\/asks per marker orderbook","tags":["Market Data"],"parameters":[{"name":"ticker_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/spot\/cg\/historical_trades":{"get":{"operationId":"marketCoingecko.historicalTrades","tags":["Market Data"],"parameters":[{"name":"ticker_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"bids":{"type":"array","items":{"$ref":"#\/components\/schemas\/TransactionCoingecko"}},"asks":{"type":"array","items":{"$ref":"#\/components\/schemas\/TransactionCoingecko"}}},"required":["bids","asks"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/api\/bridge\/notifications":{"get":{"operationId":"bridge.notifications.index","summary":"In-app notification feed with the unread counter","tags":["Notification"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"notifications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event":{},"data":{"type":"array","items":{}},"read":{"type":"boolean"},"created_at":{"type":"string"}},"required":["id","event","data","read","created_at"]}},"unread_count":{"type":"integer"},"has_more":{"type":"boolean"},"page":{"type":"integer"}},"required":["notifications","unread_count","has_more","page"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/notifications\/read":{"post":{"operationId":"bridge.notifications.read","summary":"Mark notifications as read (specific ids or everything)","tags":["Notification"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"unread_count":{"type":"integer"}},"required":["unread_count"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/options\/open":{"get":{"operationId":"getOpenOptionsContracts","description":"Retrieves all active (open) options contracts for the authenticated user.\nActive contracts are those that have not yet expired.","summary":"Get Open Options Contracts","tags":["Options Trading"],"parameters":[{"name":"market","in":"query","description":"Filter by market pair name","schema":{"type":"string"},"example":"BTC-USDT"}],"responses":{"200":{"description":"`OptionCollection`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/OptionCollection"},"success":{"type":"boolean"}},"required":["data","success"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/options\/trades":{"get":{"operationId":"getOptionsTradeHistory","description":"Retrieves the complete options trading history for the authenticated user.\nIncludes both winning and losing contracts with their final PNL.\n\n**Contract Statuses:** active, won, lost","summary":"Get Options Trade History","tags":["Options Trading"],"parameters":[{"name":"market","in":"query","description":"Filter by market pair name","schema":{"type":"string"},"example":"BTC-USDT"}],"responses":{"200":{"description":"`OptionCollection`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/OptionCollection"},"success":{"type":"boolean"}},"required":["data","success"]}}}}}}},"\/orders\/cancel":{"post":{"operationId":"cancelSpotOrder","description":"Cancels an existing open spot order. Only pending orders can be cancelled.\nThe locked balance will be returned to the user's available balance.","summary":"Cancel Spot Order","tags":["Spot Trading"],"requestBody":{"content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/OrderCancelRequest"},{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"The UUID of the order to cancel","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["uuid"]}]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"message":{"type":"string","enum":["request processed","request_was_not_processed"]}},"required":["message"]},{"type":"string"}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/orders\/open":{"get":{"operationId":"getOpenSpotOrders","description":"Retrieves all open (pending) spot orders for the authenticated user.\nOptionally filter by market pair.","summary":"Get Open Orders","tags":["Spot Trading"],"parameters":[{"name":"market","in":"query","description":"Filter by market pair name","schema":{"type":"string"},"example":"BTC-USDT"}],"responses":{"200":{"description":"`OrderCollection`","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/OrderCollection"},"success":{"type":"boolean"}},"required":["data","success"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/orders\/history":{"get":{"operationId":"getOrderHistory","description":"Retrieves the complete order history for the authenticated user.\nIncludes both completed and cancelled orders with their associated transactions.","summary":"Get Order History","tags":["Spot Trading"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/orders\/trades":{"get":{"operationId":"getTradeHistory","description":"Retrieves the complete trade (transaction) history for the authenticated user.\nEach trade represents an executed fill of an order.","summary":"Get Trade History","tags":["Spot Trading"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/orders":{"post":{"operationId":"createSpotOrder","description":"Places a new spot order on the exchange. Supports limit, market order types.\nFor market buy orders, use `quoteQuantity` to specify the amount of quote currency to spend.\nFor all other orders, use `quantity` to specify the base currency amount.\n\n**Precision Rules:**\n- `quantity` must respect the market's `base_precision` (e.g., for base_precision=5, max 5 decimal places)\n- `price` and `quoteQuantity` must respect the market's `quote_precision` (e.g., for quote_precision=2, max 2 decimal places)\n\n**Order Types:**\n- `limit`: Executes at specified price or better. Requires `price` and `quantity`.\n- `market`: Executes immediately at best available price. Buy orders require `quoteQuantity`, sell orders require `quantity`.\n\n**Order Side:**\n - buy\n - sell","summary":"Create Spot Order","tags":["Spot Trading"],"requestBody":{"content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/OrderStoreRequest"},{"type":"object","properties":{"market":{"type":"string","description":"The market pair name","example":"BTC-USDT"},"type":{"type":"string","description":"Order type: \"limit\" or \"market\"","example":"limit"},"side":{"type":"string","description":"Order side: \"buy\" or \"sell\"","example":"buy"},"quantity":{"type":"string","description":"Quantity of base currency. Required for limit\/sell market orders","example":"0.12345"},"price":{"type":"string","description":"Limit price. Required for limit orders","example":"50000.12"},"quoteQuantity":{"type":"string","description":"Amount of quote currency. Required for market buy orders","example":"1000.50"}},"required":["market","type","side"]}]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"string"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/stakings":{"get":{"operationId":"listStakingPlans","description":"Retrieves all available staking plans\/products that users can subscribe to.","summary":"List Available Staking Plans","tags":["Staking"],"parameters":[{"name":"sort","in":"query","description":"Optional sorting parameter","schema":{"type":"string"},"example":"apy_desc"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"stakings":{"$ref":"#\/components\/schemas\/StakingCollection"},"sort":{}},"required":["stakings","sort"]}}}}}}},"\/staking":{"get":{"operationId":"getStakingPlanDetails","description":"Retrieves detailed information about a specific staking plan.","summary":"Get Staking Plan Details","tags":["Staking"],"parameters":[{"name":"id","in":"query","required":true,"description":"The staking plan ID","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"staking":{"$ref":"#\/components\/schemas\/Staking"}},"required":["staking"]},{"type":"string"}]}}}}}}},"\/stakings\/my":{"get":{"operationId":"getMyStakingPositions","description":"Retrieves all staking positions for the authenticated user.","summary":"Get My Staking Positions","tags":["Staking"],"parameters":[{"name":"sort","in":"query","description":"Optional sorting parameter","schema":{"type":"string"},"example":"created_at_desc"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"stakings":{"$ref":"#\/components\/schemas\/StakingUserCollection"},"sort":{}},"required":["stakings","sort"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/staking\/submit":{"post":{"operationId":"staking.api.submit","tags":["Staking"],"requestBody":{"content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/StakingPurchaseRequest"},{"type":"object","properties":{"days":{"type":"string"}}}]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"404":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"Wallet not found"}},"required":["success","message"]},{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"Staking not found"}},"required":["success","message"]}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/staking\/redeem":{"post":{"operationId":"staking.api.redeem","tags":["Staking"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StakingRedeemRequest"}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/staking\/redemption\/calculate":{"post":{"operationId":"staking.api.redemption.calculate","tags":["Staking"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"value_date":{"type":"string"},"redemption_date":{"type":"string"}},"required":["value_date","redemption_date"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/ping":{"get":{"operationId":"bridge.ping","summary":"Health check for the Bridge client API","tags":["Status"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"time":{"type":"string"}},"required":["status","time"]}},"required":["success","data"]}}}}}}},"\/transactions\/deposits\/crypto":{"get":{"operationId":"getCryptoDepositTransactions","description":"Retrieves cryptocurrency deposit transactions for the authenticated user.\n\n`status` is the on-chain verdict: an AML-held deposit stays `confirmed` while the\nfunds never reach the balance. Use `credited` \u2014 the flag and the status filter \u2014\nto select deposits whose money is actually available.","summary":"Get Crypto Deposit Transactions","tags":["Transactions"],"parameters":[{"name":"page","in":"query","schema":{"type":["integer","null"],"minimum":1}},{"name":"status","in":"query","schema":{"type":["string","null"],"enum":["credited","completed","confirmed","pending"]}},{"name":"currency","in":"query","schema":{"type":["integer","null"],"minimum":1}},{"name":"txn","in":"query","schema":{"type":["string","null"],"maxLength":500}},{"name":"limit","in":"query","schema":{"type":["integer","null"],"minimum":1,"maximum":100}},{"name":"period","in":"query","schema":{"type":["string","null"],"enum":["today","yesterday","24h","week","month","3months","6months","year"]}},{"name":"from","in":"query","schema":{"type":["string","null"],"format":"date-time"}},{"name":"to","in":"query","schema":{"type":["string","null"],"format":"date-time"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/transactions\/withdrawals\/crypto":{"get":{"operationId":"getCryptoWithdrawalTransactions","description":"Retrieves cryptocurrency withdrawal transactions for the authenticated user.\nPeriod options: today, yesterday, week, month, year","summary":"Get Crypto Withdrawal Transactions","tags":["Transactions"],"parameters":[{"name":"period","in":"query","description":"Filter by time period: today, yesterday, week, month, year","schema":{"type":"string"},"example":"month"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"items":{"type":"string"}},"required":["items"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/transactions\/trades":{"get":{"operationId":"getSpotTradeTransactions","description":"Retrieves spot trading transaction history for the authenticated user.\nPeriod options: today, yesterday, week, month, year","summary":"Get Spot Trade Transactions","tags":["Transactions"],"parameters":[{"name":"period","in":"query","description":"Filter by time period: today, yesterday, week, month, year","schema":{"type":"string"},"example":"week"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"items":{"type":"string"}},"required":["items"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/transactions\/futures-trades":{"get":{"operationId":"getFuturesTradeTransactions","description":"Retrieves futures trading transaction history for the authenticated user.\nPeriod options: today, yesterday, week, month, year","summary":"Get Futures Trade Transactions","tags":["Transactions"],"parameters":[{"name":"period","in":"query","description":"Filter by time period: today, yesterday, week, month, year","schema":{"type":"string"},"example":"week"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"items":{"type":"string"}},"required":["items"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/transactions\/orders":{"get":{"operationId":"getOrderTransactions","description":"Retrieves order history for the authenticated user.\nPeriod options: today, yesterday, week, month, year","summary":"Get Order Transactions","tags":["Transactions"],"parameters":[{"name":"period","in":"query","description":"Filter by time period: today, yesterday, week, month, year","schema":{"type":"string"},"example":"month"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"items":{"type":"string"}},"required":["items"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/transactions\/launchpads":{"get":{"operationId":"getLaunchpadTransactions","description":"Retrieves launchpad\/IEO purchase transactions for the authenticated user.\nPeriod options: today, yesterday, week, month, year","summary":"Get Launchpad Transactions","tags":["Transactions"],"parameters":[{"name":"period","in":"query","description":"Filter by time period: today, yesterday, week, month, year","schema":{"type":"string"},"example":"year"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"items":{"type":"string"}},"required":["items"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/wallets\/getAddress":{"get":{"operationId":"getDepositAddress","description":"Generates or retrieves a deposit address for a specific cryptocurrency and network.","summary":"Get Deposit Address","tags":["Wallet"],"parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"}},{"name":"network","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"string"}}}},"403":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"Deposits are not allowed for this network"}},"required":["success","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/wallets\/balance":{"get":{"operationId":"getCurrencyBalance","description":"Retrieves the balance for a specific currency.\nCan return either funding (account) or trading balance.","summary":"Get Currency Balance","tags":["Wallet"],"parameters":[{"name":"currency","in":"query","required":true,"description":"The currency ID","schema":{"type":"integer"},"example":1},{"name":"type","in":"query","description":"Balance type: \"account\" (funding) or \"trade\" (trading)","schema":{"type":"string"},"example":"trade"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"balance":{"type":"string"}},"required":["success","balance"]}}}},"422":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"Wallet not found"}},"required":["success","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/wallets\/deposit\/networks":{"get":{"operationId":"loadCurrencyNetworks","description":"Retrieves available networks for a specific currency.","summary":"Load Currency Networks","tags":["Wallet"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"The currency symbol","schema":{"type":"string"},"example":"USDT"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"string"},{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/wallets\/deposits\/{type}":{"get":{"operationId":"getCryptoDeposits","description":"Retrieves cryptocurrency deposit history for the authenticated user.\nIncludes pending, confirmed, and failed deposits.\n\n`status` is the on-chain verdict: an AML-held deposit stays `confirmed` while the\nfunds never reach the balance. Use `credited` \u2014 the flag and the status filter \u2014\nto select deposits whose money is actually available.","summary":"Get Crypto Deposits","tags":["Wallet"],"parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["coin","all"]}},{"name":"status","in":"query","schema":{"type":["string","null"],"enum":["credited","completed","confirmed","pending"]}},{"name":"currency","in":"query","schema":{"type":["integer","null"],"minimum":1}},{"name":"txn","in":"query","schema":{"type":["string","null"],"maxLength":500}},{"name":"limit","in":"query","schema":{"type":["integer","null"],"minimum":1,"maximum":1000}},{"name":"period","in":"query","schema":{"type":["string","null"],"enum":["today","yesterday","24h","week","month","3months","6months","year"]}},{"name":"from","in":"query","schema":{"type":["string","null"],"format":"date-time"}},{"name":"to","in":"query","schema":{"type":["string","null"],"format":"date-time"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"422":{"$ref":"#\/components\/responses\/ValidationException"}}}},"\/wallets\/fiat-deposits\/{type}":{"get":{"operationId":"getFiatDeposits","description":"Retrieves fiat currency deposit history for the authenticated user.\nIncludes deposits made via bank transfer, card payments, etc.","summary":"Get Fiat Deposits","tags":["Wallet"],"parameters":[{"name":"type","in":"path","required":true,"description":"**Optional**","schema":{"type":"string","default":"all"},"x-optional":true}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/wallets\/deposit\/crypto":{"get":{"operationId":"getDepositInfo","description":"Retrieves deposit information for a specific cryptocurrency.\nIncludes available networks, minimum deposit amounts, and currency details.","summary":"Get Deposit Info","tags":["Wallet"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"The currency symbol","schema":{"type":"string"},"example":"BTC"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"symbol":{},"currency":{"$ref":"#\/components\/schemas\/Currency"},"networks":{"type":"string"}},"required":["symbol","currency","networks"]},{"type":"string"}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/wallets\/withdraw\/crypto":{"get":{"operationId":"getWithdrawInfo","description":"Retrieves withdrawal information for a specific cryptocurrency.\nIncludes available networks, fees, limits, and remaining daily limit.","summary":"Get Withdrawal Info","tags":["Wallet"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"The currency symbol","schema":{"type":"string"},"example":"BTC"}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"string"},{"type":"object","properties":{"limit":{"type":"string"},"symbol":{},"currency":{"$ref":"#\/components\/schemas\/Currency"},"networks":{"type":"string"}},"required":["limit","symbol","currency","networks"]}]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/wallets\/withdrawals\/{type}":{"get":{"operationId":"getCryptoWithdrawals","description":"Retrieves cryptocurrency withdrawal history for the authenticated user.\nIncludes pending, processing, completed, and rejected withdrawals.","summary":"Get Crypto Withdrawals","tags":["Wallet"],"parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","default":"coin"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/wallets\/withdraw":{"post":{"operationId":"withdrawCrypto","description":"Initiates a cryptocurrency withdrawal to an external address.\nWithdrawal will be processed after security verification.","summary":"Withdraw Cryptocurrency","tags":["Wallet"],"requestBody":{"content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/WithdrawRequest"},{"type":"object","properties":{"symbol":{"type":"string","description":"The currency symbol to withdraw","example":"BTC"},"network":{"type":"integer","description":"The network ID to use for withdrawal","example":1},"address":{"type":"string","description":"The destination wallet address","example":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"},"amount":{"type":"string","description":"The amount to withdraw","example":"0.5"},"payment_id":{"type":"string","description":"Optional payment ID\/memo for certain networks","example":"12345"}},"required":["symbol","network","address","amount"]}]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"anyOf":[{"type":"object","properties":{"result":{"type":"boolean"}},"required":["result"]},{"type":"string"}]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/wallets\/transfer":{"post":{"operationId":"transferBetweenAccounts","description":"Transfers funds between Funding (wallet) and Trading accounts.\nA commission may apply when transferring from Trading to Funding.\n\n**Transfer Directions:**\n- `to_trade`: Transfer from Funding to Trading account\n- `to_funding`: Transfer from Trading to Funding account (may incur commission)","summary":"Transfer Between Accounts","tags":["Wallet"],"requestBody":{"content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/TransferRequest"},{"type":"object","properties":{"currency_id":{"type":"integer","description":"The currency ID to transfer","example":1},"amount":{"type":"string","description":"The amount to transfer","example":"100.00"},"direction":{"type":"string","description":"Transfer direction: \"to_trade\" or \"to_funding\"","example":"to_trade"}},"required":["currency_id","amount","direction"]}]}}}},"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"commission":{"type":"string"},"credited":{"type":"string"},"balances":{"type":"object","properties":{"balance_in_wallet":{"type":"string"},"balance_in_trade":{"type":"string"}},"required":["balance_in_wallet","balance_in_trade"]}},"required":["success","commission","credited","balances"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"404":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","const":"Wallet not found"}},"required":["success","message"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"},"403":{"$ref":"#\/components\/responses\/AuthorizationException"}}}},"\/wallets\/fiat-withdrawals":{"get":{"operationId":"getFiatWithdrawals","description":"Retrieves fiat currency withdrawal history for the authenticated user.\nIncludes withdrawals to bank accounts and other fiat payment methods.","summary":"Get Fiat Withdrawals","tags":["Wallet"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/wallets":{"get":{"operationId":"getAllWallets","description":"Retrieves all wallets for the authenticated user.\nEach wallet contains balance information for both funding and trading accounts.","summary":"Get All Wallets","tags":["Wallet"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/networks":{"get":{"operationId":"getAvailableNetworks","description":"Retrieves all available blockchain networks for deposits and withdrawals.\nEach network includes its name and supported features.","summary":"Get Available Networks","tags":["Wallet"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"integer","const":200}}}}}}},"\/api\/bridge\/withdraw\/info":{"get":{"operationId":"bridge.withdrawals.info","summary":"Tariff, limits and network availability for the withdraw form (SPEC \u00a712)","tags":["Withdrawal"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"asset":{"type":"string"},"enabled":{"type":"boolean"},"fee":{"type":"object","properties":{"percent":{"type":"string"},"fixed":{"type":"string"}},"required":["percent","fixed"]},"limits":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":["string","null"]}},"required":["min","max"]},"requires_totp_setup":{"type":"string"},"networks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"available":{"type":"string"}},"required":["id","slug","name","available"]}}},"required":["asset","enabled","fee","limits","requires_totp_setup","networks"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/withdrawals":{"get":{"operationId":"bridge.withdrawals.index","summary":"Withdrawal history with fee breakdown and timelines","tags":["Withdrawal"],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"withdrawals":{"type":"array","items":{}},"has_more":{"type":"boolean"},"page":{"type":"integer"}},"required":["withdrawals","has_more","page"]}},"required":["success","data"]}}}},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}},"post":{"operationId":"bridge.withdrawals.store","summary":"Create a withdrawal (SPEC \u00a712\u2013\u00a714). Kill switch + mandatory TOTP","tags":["Withdrawal"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StoreWithdrawalRequest"}}}},"responses":{"201":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"withdrawal":{"type":"array","items":{}}},"required":["withdrawal"]}},"required":["success","data"]}}}},"503":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string","const":"WITHDRAWALS_DISABLED"},"message":{"type":"string","const":"Withdrawals are temporarily unavailable."}},"required":["code","message"]}},"required":["success","error"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}}}},"\/api\/bridge\/withdrawals\/{withdrawal}\/cancel":{"post":{"operationId":"bridge.withdrawals.cancel","summary":"Cancel while still queued (SPEC \u00a72). v2 rows are cancellable in","tags":["Withdrawal"],"parameters":[{"name":"withdrawal","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"withdrawal":{"type":"array","items":{}}},"required":["withdrawal"]}},"required":["success","data"]}}}},"422":{"$ref":"#\/components\/responses\/ValidationException"},"401":{"$ref":"#\/components\/responses\/AuthenticationException"}},"description":"Cancel while still queued (SPEC \u00a72). v2 rows are cancellable in\nawaiting_whitelist \/ approved-before-claim; legacy rows while their\ncore row is in waiting_approval"}}},"components":{"securitySchemes":{"http":{"type":"http","scheme":"bearer","bearerFormat":"Sanctum"}},"schemas":{"AssetCmc":{"type":"object","properties":{"name":{"type":"string"},"unified_cryptoasset_id":{"type":"string"},"can_withdraw":{"type":"string"},"can_deposit":{"type":"string"},"min_withdraw":{"type":"string"},"max_withdraw":{"type":"string"},"maker_fee":{"type":"string"},"taker_fee":{"type":"string"}},"required":["name","unified_cryptoasset_id","can_withdraw","can_deposit","min_withdraw","max_withdraw","maker_fee","taker_fee"],"title":"AssetCmc"},"CandleCollection":{"type":"array","items":{"type":"string"},"title":"CandleCollection"},"ConfirmLinkEmailRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255},"code":{"type":"string"},"twofa":{"type":["string","null"]}},"required":["email","code"],"title":"ConfirmLinkEmailRequest"},"Currency":{"type":"object","properties":{"name":{"type":"string"},"symbol":{"type":"string"},"fullname":{"type":"string"},"logo":{"type":"string"},"full_logo_path":{"type":"string"},"decimals":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"min_deposit_confirmation":{"type":"string"},"deposit_status":{"type":"string"},"withdraw_status":{"type":"string"},"deposit_fee":{"type":"string"},"deposit_fee_fixed":{"type":"string"},"deposit_fee_erc":{"type":"string"},"deposit_fee_bep":{"type":"string"},"deposit_fee_trc":{"type":"string"},"deposit_fee_sol":{"type":"string"},"deposit_fee_matic":{"type":"string"},"deposit_fee_erc_fixed":{"type":"string"},"deposit_fee_bep_fixed":{"type":"string"},"deposit_fee_trc_fixed":{"type":"string"},"deposit_fee_sol_fixed":{"type":"string"},"deposit_fee_matic_fixed":{"type":"string"},"withdraw_fee":{"type":"string"},"withdraw_fee_fixed":{"anyOf":[{"type":"string"},{"type":"integer","enum":[0]}]},"withdraw_fee_erc":{"type":"string"},"withdraw_fee_bep":{"type":"string"},"withdraw_fee_trc":{"type":"string"},"withdraw_fee_sol":{"type":"string"},"withdraw_fee_matic":{"type":"string"},"withdraw_fee_erc_fixed":{"anyOf":[{"type":"string"},{"type":"integer","enum":[0]}]},"withdraw_fee_bep_fixed":{"anyOf":[{"type":"string"},{"type":"integer","enum":[0]}]},"withdraw_fee_sol_fixed":{"anyOf":[{"type":"string"},{"type":"integer","enum":[0]}]},"withdraw_fee_trc_fixed":{"anyOf":[{"type":"string"},{"type":"integer","enum":[0]}]},"withdraw_fee_matic_fixed":{"anyOf":[{"type":"string"},{"type":"integer","enum":[0]}]},"min_deposit":{"type":"string"},"max_deposit":{"type":"string"},"min_withdraw":{"type":"string"},"max_withdraw":{"type":"string"},"has_payment_id":{"type":"string"},"networks":{"$ref":"#\/components\/schemas\/NetworkCollection"}},"required":["name","symbol","fullname","logo","full_logo_path","decimals","type","status","min_deposit_confirmation","deposit_status","withdraw_status","deposit_fee","deposit_fee_fixed","deposit_fee_erc","deposit_fee_bep","deposit_fee_trc","deposit_fee_sol","deposit_fee_matic","deposit_fee_erc_fixed","deposit_fee_bep_fixed","deposit_fee_trc_fixed","deposit_fee_sol_fixed","deposit_fee_matic_fixed","withdraw_fee","withdraw_fee_fixed","withdraw_fee_erc","withdraw_fee_bep","withdraw_fee_trc","withdraw_fee_sol","withdraw_fee_matic","withdraw_fee_erc_fixed","withdraw_fee_bep_fixed","withdraw_fee_sol_fixed","withdraw_fee_trc_fixed","withdraw_fee_matic_fixed","min_deposit","max_deposit","min_withdraw","max_withdraw","has_payment_id","networks"],"title":"Currency"},"GoogleLoginRequest":{"type":"object","properties":{"id_token":{"type":"string"},"device_name":{"type":["string","null"],"maxLength":64}},"required":["id_token"],"title":"GoogleLoginRequest"},"Launchpad":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"network":{"type":"string","enum":["BEP-20","ERC-20"]},"network_symbol":{"type":"string","enum":["BNB","ETH"]},"description":{"type":"string"},"currency":{"type":"string"},"currency_symbol":{"type":"string"},"currency_logo":{"type":["string","null"]},"soft_cap":{"type":"string"},"hard_cap":{"type":"string"},"rate":{"type":"string"},"min_buy":{"type":"string"},"max_buy":{"type":"string"},"raised_amount":{"type":"string"},"filled":{"type":"string"},"status":{"type":"string"},"start_time":{"type":"string"},"end_time":{"type":"string"}},"required":["id","name","network","network_symbol","description","currency","currency_symbol","currency_logo","soft_cap","hard_cap","rate","min_buy","max_buy","raised_amount","filled","status","start_time","end_time"],"title":"Launchpad"},"LaunchpadCollection":{"type":"array","items":{"type":"string"},"title":"LaunchpadCollection"},"LaunchpadPurchaseRequest":{"type":"object","properties":{"id":{"type":"integer"},"amount":{"type":"number"}},"required":["id","amount"],"title":"LaunchpadPurchaseRequest"},"LinkGoogleRequest":{"type":"object","properties":{"id_token":{"type":"string"},"twofa":{"type":["string","null"]}},"required":["id_token"],"title":"LinkGoogleRequest"},"LinkTelegramRequest":{"type":"object","properties":{"init_data":{"type":"string"},"widget_data":{"type":"array","items":{"type":"string"}},"twofa":{"type":["string","null"]}},"title":"LinkTelegramRequest"},"LockCardRequest":{"type":"object","description":"Validates the route parameter `id` for the POST \/api\/v1\/cards\/{id}\/lock endpoint.\nThe controller resolves user_id and card_id from the card model \u2014 no body params needed.","properties":{"id":{"type":"integer","minimum":1}},"required":["id"],"title":"LockCardRequest"},"Market":{"type":"object","properties":{"name":{"type":"string"},"s":{"type":"string"},"sanitized_name":{"type":"string"},"base_currency":{"type":"string"},"base_currency_name":{"type":"string"},"base_currency_type":{"type":"string"},"base_currency_logo":{"anyOf":[{"type":"string"},{"type":"string","enum":[""]}]},"base_currency_discord":{"type":"string"},"base_currency_twitter":{"type":"string"},"base_currency_website":{"type":"string"},"quote_currency":{"type":"string"},"quote_currency_name":{"type":"string"},"quote_currency_type":{"type":"string"},"base_precision":{"type":"string"},"quote_precision":{"type":"string"},"min_trade_size":{"type":"string"},"max_trade_size":{"type":"string"},"min_trade_value":{"type":"string"},"max_trade_value":{"type":"string"},"base_ticker_size":{"type":"string"},"quote_ticker_size":{"type":"string"},"status":{"type":"string"},"ratio":{"type":"string"},"ratio_b":{"type":"string"},"has_futures":{"type":"string"},"has_options":{"type":"string"},"trade_status":{"type":"string"},"buy_order_status":{"type":"string"},"sell_order_status":{"type":"string"},"cancel_order_status":{"type":"string"},"chart_enabled":{"type":"string"},"listed":{"type":"integer"},"custom_market_path":{"type":"string"},"last":{"type":"string"},"change":{"anyOf":[{"type":"number"},{"type":"string"}]},"high":{"type":"string"},"low":{"type":"string"},"volume":{"type":"string"},"qVolume":{"type":"string"},"fee":{"type":"string"},"opt_min":{"type":"string"},"opt_max":{"type":"string"},"is_meme":{"type":"string"},"is_layer_one":{"type":"string"},"is_layer_two":{"type":"string"},"is_innovation":{"type":"string"},"is_ai":{"type":"string"},"is_defi":{"type":"string"},"is_gamefi":{"type":"string"},"is_pow":{"type":"string"},"is_fan_tokens":{"type":"string"},"is_nft":{"type":"string"},"listed_at":{"type":"string"}},"required":["name","s","sanitized_name","base_currency","base_currency_name","base_currency_type","base_currency_logo","base_currency_discord","base_currency_twitter","base_currency_website","quote_currency","quote_currency_name","quote_currency_type","base_precision","quote_precision","min_trade_size","max_trade_size","min_trade_value","max_trade_value","base_ticker_size","quote_ticker_size","status","ratio","ratio_b","has_futures","has_options","trade_status","buy_order_status","sell_order_status","cancel_order_status","chart_enabled","listed","custom_market_path","last","change","high","low","volume","qVolume","fee","opt_min","opt_max","is_meme","is_layer_one","is_layer_two","is_innovation","is_ai","is_defi","is_gamefi","is_pow","is_fan_tokens","is_nft","listed_at"],"title":"Market"},"MarketCmc":{"type":"object","properties":{"trading_pairs":{"type":"string"},"base_currency":{"type":"string"},"quote_currency":{"type":"string"},"last_price":{"type":"string"},"lowest_ask":{"type":"string"},"highest_bid":{"type":"string"},"base_volume":{"type":"string"},"quote_volume":{"type":"string"},"price_change_percent_24h":{"type":"string"},"highest_price_24h":{"type":"string"},"lowest_price_24h":{"type":"string"}},"required":["trading_pairs","base_currency","quote_currency","last_price","lowest_ask","highest_bid","base_volume","quote_volume","price_change_percent_24h","highest_price_24h","lowest_price_24h"],"title":"MarketCmc"},"MarketCollection":{"type":"array","items":{"type":"string"},"title":"MarketCollection"},"NetworkCollection":{"type":"array","items":{"type":"string"},"title":"NetworkCollection"},"OpenFuturesOrderCollection":{"type":"array","items":{"type":"string"},"title":"OpenFuturesOrderCollection"},"OptionCollection":{"type":"array","items":{"type":"string"},"title":"OptionCollection"},"OrderCancelRequest":{"type":"object","properties":{"uuid":{"type":"string","maxLength":100}},"required":["uuid"],"title":"OrderCancelRequest"},"OrderCollection":{"type":"array","items":{"type":"string"},"title":"OrderCollection"},"OrderFuturesCancelRequest":{"type":"object","properties":{"uuid":{"type":"string","maxLength":100}},"required":["uuid"],"title":"OrderFuturesCancelRequest"},"OrderStoreRequest":{"type":"object","properties":{"market":{"type":"string"},"type":{"type":"string"},"side":{"type":"string"},"quantity":{"type":"string"},"price":{"type":"string"},"quoteQuantity":{"type":"string"},"trigger_price":{"type":"string"}},"required":["market","type","side"],"title":"OrderStoreRequest"},"PairCoingecko":{"type":"object","properties":{"id":{"type":"string"},"ticker_id":{"type":"string"},"base":{"type":"string"},"target":{"type":"string"}},"required":["id","ticker_id","base","target"],"title":"PairCoingecko"},"RequestEmailOtpRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255}},"required":["email"],"title":"RequestEmailOtpRequest"},"RequestLinkEmailOtpRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255}},"required":["email"],"title":"RequestLinkEmailOtpRequest"},"Staking":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"currency_symbol":{"type":"string"},"currency_logo":{"type":["string","null"]},"allowed_days":{"type":"string"},"rewards_percentage":{"type":"string"},"min_amount":{"type":"string"},"max_amount":{"type":"string"},"ranges":{"type":"array","items":{}},"status":{"type":"string"},"created_at":{"type":"string"}},"required":["id","currency","currency_symbol","currency_logo","allowed_days","rewards_percentage","min_amount","max_amount","ranges","status","created_at"],"title":"Staking"},"StakingCollection":{"type":"array","items":{"type":"string"},"title":"StakingCollection"},"StakingPurchaseRequest":{"type":"object","properties":{"id":{"type":"integer"},"amount":{"type":"number"}},"required":["id","amount"],"title":"StakingPurchaseRequest"},"StakingRedeemRequest":{"type":"object","properties":{"id":{"type":"integer"}},"required":["id"],"title":"StakingRedeemRequest"},"StakingUserCollection":{"type":"array","items":{"type":"string"},"title":"StakingUserCollection"},"StoreAddressBookRequest":{"type":"object","properties":{"label":{"type":"string","maxLength":64},"network_id":{"type":"integer"},"address":{"type":"string","maxLength":128},"twofa":{"type":"string"}},"required":["label","network_id","address","twofa"],"title":"StoreAddressBookRequest"},"StoreCaseMessageRequest":{"type":"object","properties":{"message":{"type":"string","maxLength":5000}},"required":["message"],"title":"StoreCaseMessageRequest"},"StoreCaseRequest":{"type":"object","properties":{"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":5000}},"required":["subject","message"],"title":"StoreCaseRequest"},"StoreWithdrawalRequest":{"type":"object","properties":{"address_book_id":{"type":"integer"},"amount":{"type":"number"},"twofa":{"type":"string"},"client_reference":{"type":["string","null"],"maxLength":64}},"required":["address_book_id","amount","twofa"],"title":"StoreWithdrawalRequest"},"TelegramLoginRequest":{"type":"object","properties":{"init_data":{"type":"string"},"widget_data":{"type":"array","items":{"type":"string"}},"device_name":{"type":["string","null"],"maxLength":64}},"title":"TelegramLoginRequest"},"TickerCmc":{"type":"array","prefixItems":[{"type":"object","properties":{"base_id":{"type":"string"},"quote_id":{"type":"string"},"last_price":{"type":"string"},"base_volume":{"type":"string"},"quote_volume":{"type":"string"},"isFrozen":{"type":"integer","enum":[0,1]}},"required":["base_id","quote_id","last_price","base_volume","quote_volume","isFrozen"]}],"minItems":1,"maxItems":1,"additionalItems":false,"title":"TickerCmc"},"TickerCoingecko":{"type":"object","properties":{"ticker_id":{"type":"string"},"base_currency":{"type":"string"},"target_currency":{"type":"string"},"last_price":{"type":"string"},"base_volume":{"type":"string"},"target_volume":{"type":"string"},"bid":{"type":"string"},"ask":{"type":"string"},"high":{"type":"string"},"low":{"type":"string"}},"required":["ticker_id","base_currency","target_currency","last_price","base_volume","target_volume","bid","ask","high","low"],"title":"TickerCoingecko"},"TransactionCmc":{"type":"object","properties":{"trade_id":{"type":"string"},"price":{"type":"string"},"base_volume":{"type":"string"},"quote_volume":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"}},"required":["trade_id","price","base_volume","quote_volume","type","timestamp"],"title":"TransactionCmc"},"TransactionCoingecko":{"type":"object","properties":{"trade_id":{"type":"string"},"price":{"type":"string"},"base_volume":{"type":"string"},"target_volume":{"type":"string"},"type":{"type":"string"},"trade_timestamp":{"type":"string"}},"required":["trade_id","price","base_volume","target_volume","type","trade_timestamp"],"title":"TransactionCoingecko"},"TransactionCollection":{"type":"array","items":{"type":"string"},"title":"TransactionCollection"},"TransferRequest":{"type":"object","properties":{"currency_id":{"type":"integer"},"amount":{"type":"number","minimum":1.0e-8},"direction":{"type":"string","enum":["to_trade","to_funding"]}},"required":["currency_id","amount","direction"],"title":"TransferRequest"},"UnlockCardRequest":{"type":"object","description":"Validates the route parameter `id` for the POST \/api\/v1\/cards\/{id}\/unlock endpoint.\nThe controller resolves user_id and card_id from the card model \u2014 no body params needed.","properties":{"id":{"type":"integer","minimum":1}},"required":["id"],"title":"UnlockCardRequest"},"UploadKybDocumentRequest":{"type":"object","properties":{"type":{"type":"string","enum":["certificate_of_incorporation","registry_extract","articles_of_association","register_of_directors","register_of_shareholders","ownership_structure","ubo_list","director_id","ubo_id","company_proof_of_address","director_proof_of_address","business_licence","source_of_funds_docs","bank_statement","financial_statements","contracts_invoices","other"]},"file":{"type":"string","format":"binary","contentMediaType":"application\/octet-stream","maxLength":15360}},"required":["type","file"],"title":"UploadKybDocumentRequest"},"VerifyEmailOtpRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255},"code":{"type":"string"},"device_name":{"type":["string","null"],"maxLength":64}},"required":["email","code"],"title":"VerifyEmailOtpRequest"},"WithdrawRequest":{"type":"object","properties":{"symbol":{"type":"string"},"address":{"type":"string","maxLength":255},"network":{"type":"string"},"payment_id":{"type":["integer","null"],"maximum":4294967295},"amount":{"type":"number"}},"required":["symbol","address","network","amount"],"title":"WithdrawRequest"}},"responses":{"AuthenticationException":{"description":"Unauthenticated","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}}}},"ValidationException":{"description":"Validation error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Errors overview."},"errors":{"type":"object","description":"A detailed description of each field that failed validation.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["message","errors"]}}}},"AuthorizationException":{"description":"Authorization error","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}}}},"NotFoundHttpException":{"description":"Not found","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}}}},"ModelNotFoundException":{"description":"Not found","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}}}}}},"tags":[{"name":"Cards","description":"## Card Issuer API\n\nIssue and manage virtual cards for your end users \u2014 create cardholders, run KYC, issue cards, fund\nthem from your platform wallet, and manage their lifecycle. Base path: **`\/api\/v1\/cards`**.\n\n- **Authentication:** Laravel Sanctum \u2014 `Authorization: Bearer <token>` on every request.\n- **Responses:** JSON. On error the payload is `{ \"success\": false, \"error\": { \"code\": \"...\", \"message\": \"...\" } }`.\n\nThe endpoints are generated from the API itself, so they always match the live contract. This\noverview adds the integration context the reference cannot express on its own \u2014 the money flow, the\ntwo-stage approval model, card statuses, and error codes.\n\n## Authentication\n\nUse **Laravel Sanctum** with a personal access token for your platform account (not the Crypto\nAcquiring HMAC keys).\n\n```http\nAuthorization: Bearer <your_sanctum_token>\nAccept: application\/json\n```\n\n## Products, fees and your wallet\n\nEvery **paid** operation is charged **from your platform wallet**, in the **currency** you pass in the\nrequest body \u2014 **`USDT`** or **`USDC`** (default `USDT`). Keep a wallet for that currency funded to\ncover the amount **plus fees** before each paid call.\n\nRead the catalog first \u2014 [`GET \/api\/v1\/cards\/config`](#exchange-api\/tag\/cards\/GET\/cards\/config) returns\nthe available card products, their issuance (`api_activation_fee`) and top-up fees, and top-up min\/max\nlimits. Fees are defined per product.\n\n| Paid operation | What is charged |\n|---|---|\n| `POST \/api\/v1\/cards\/cardholders` | Cardholder-creation fee (covers the **first** card's issuance). |\n| `POST \/api\/v1\/cards\/cardholders\/{id}\/apply` | Issuance fee for the **second and later** cards (the first card is already covered above). |\n| `POST \/api\/v1\/cards\/{id}\/topup` | The top-up `amount` **plus** the product top-up fee. |\n\n> Check your wallet balance up front \u2014 via the dashboard or the wallet API \u2014 before each paid call;\n> don't rely only on an after-the-fact error. No wallet for the currency (or an unsupported currency)\n> returns `WALLET_ERROR`; short funds return `INSUFFICIENT_BALANCE`. If a card application fails after\n> the fee was taken, the fee is returned to your wallet automatically.\n\nRead-only calls and `activate`, `lock`, `unlock`, `info` and `audit-status` are **free**.\n\n## Integration flow\n\n1. **Read the catalog** \u2014 [`GET \/api\/v1\/cards\/config`](#exchange-api\/tag\/cards\/GET\/cards\/config)\n   Pick a `product_key` and learn its fees and top-up limits.\n\n2. **Create a cardholder** \u2014 [`POST \/api\/v1\/cards\/cardholders`](#exchange-api\/tag\/cards\/POST\/cards\/cardholders)\n   Send the person's profile, address and (unless KYC is disabled for your setup) an identity\n   `document` as base64 data-URI images (JPEG\/PNG). Charges the cardholder-creation fee in `currency`.\n   Returns the internal cardholder `id`.\n\n3. **Upload \/ upgrade KYC if needed** \u2014 [`POST \/api\/v1\/cards\/cardholders\/{id}\/upload-kyc`](#exchange-api\/tag\/cards\/POST\/cards\/cardholders\/{id}\/upload-kyc)\n   Use this when the cardholder's KYC is partial or was refused and you need to (re)submit documents.\n\n4. **Check the cardholder** \u2014 [`GET \/api\/v1\/cards\/cardholders\/{id}`](#exchange-api\/tag\/cards\/GET\/cards\/cardholders\/{id})\n   Watch **`kyc_status`** and **`requires_approval`** \u2014 they decide whether you can issue and top up\n   right away (see *Approval model*).\n\n5. **Apply for a card** \u2014 [`POST \/api\/v1\/cards\/cardholders\/{id}\/apply`](#exchange-api\/tag\/cards\/POST\/cards\/cardholders\/{id}\/apply)\n   Send `phone_area_code`, `phone_number` and the `embossed_name`. Returns a **`request_id`** for\n   polling. The first card carries no extra fee here; subsequent cards are charged.\n\n6. **Poll the issuance decision** \u2014 [`POST \/api\/v1\/cards\/audit-status`](#exchange-api\/tag\/cards\/POST\/cards\/audit-status)\n   Send the `request_id` and repeat until the status is final. The card then gets its external\n   **`card_id`**.\n\n7. **Activate the card** \u2014 [`POST \/api\/v1\/cards\/{id}\/activate`](#exchange-api\/tag\/cards\/POST\/cards\/{id}\/activate)\n   Virtual cards often auto-activate; call this when the card reports it needs activation. No charge.\n\n8. **Top up** \u2014 [`POST \/api\/v1\/cards\/{id}\/topup`](#exchange-api\/tag\/cards\/POST\/cards\/{id}\/topup)\n   Charges `amount` + top-up fee from your wallet in `currency`.\n\n9. **Operate the card**\n   - [`GET \/api\/v1\/cards\/{id}`](#exchange-api\/tag\/cards\/GET\/cards\/{id}) \u2014 status, balance and limits (synced from the provider)\n   - [`GET \/api\/v1\/cards\/{id}\/transactions`](#exchange-api\/tag\/cards\/GET\/cards\/{id}\/transactions) \u2014 movements\n   - [`GET \/api\/v1\/cards\/{id}\/spending-summary`](#exchange-api\/tag\/cards\/GET\/cards\/{id}\/spending-summary) \u2014 daily spend vs. limit\n   - [`POST \/api\/v1\/cards\/{id}\/info`](#exchange-api\/tag\/cards\/POST\/cards\/{id}\/info) \u2014 refresh status\/balance and the `can_*` hints\n   - [`POST \/api\/v1\/cards\/{id}\/sensitive-info`](#exchange-api\/tag\/cards\/POST\/cards\/{id}\/sensitive-info) \u2014 short-lived PAN \/ expiry \/ CVV\n   - [`POST \/api\/v1\/cards\/{id}\/lock`](#exchange-api\/tag\/cards\/POST\/cards\/{id}\/lock) and [`POST \/api\/v1\/cards\/{id}\/unlock`](#exchange-api\/tag\/cards\/POST\/cards\/{id}\/unlock) \u2014 temporary block \/ unblock\n\nList endpoints (all paginated with `page` \/ `per_page`):\n[`GET \/api\/v1\/cards`](#exchange-api\/tag\/cards\/GET\/cards) (all your cards),\n[`GET \/api\/v1\/cards\/cardholders`](#exchange-api\/tag\/cards\/GET\/cards\/cardholders) (your cardholders),\n[`GET \/api\/v1\/cards\/cardholders\/{id}\/cards`](#exchange-api\/tag\/cards\/GET\/cards\/cardholders\/{id}\/cards) (one cardholder's cards).\n\n### Identifiers\n\n| Field | Meaning |\n|---|---|\n| `id` | Our internal cardholder \/ card id \u2014 used in every `\/{id}` path. Integer. |\n| `request_id` | Returned by `apply`; used to poll `audit-status`. |\n| `card_id` | The card's external id; appears once issuance succeeds. |\n\n## Approval model \u2014 two independent stages\n\nKeep these two apart.\n\n### 1. Cardholder \u2014 `requires_approval`\n\nIf the cardholder's **address country** falls under the platform's internal rules, the fully-automatic\nsingle-request document flow is not used for that country.\n\n- The create call is still accepted (per the validation contract).\n- The response carries **`status: \"pending_approval\"`** and **`requires_approval: true`** with an\n  explanatory `message`.\n- While in this state, operations such as top-up return **`CARDHOLDER_PENDING_APPROVAL`**. Poll\n  [`GET \/api\/v1\/cards\/cardholders\/{id}`](#exchange-api\/tag\/cards\/GET\/cards\/cardholders\/{id}) and key off\n  `requires_approval` until the platform clears it.\n\n### 2. Card application \u2014 `audit-status`\n\nAfter `apply`, issuance goes through a review stage tracked by **`request_id`**.\n\n- Until it is approved, `card_id` may be empty.\n- Poll [`POST \/api\/v1\/cards\/audit-status`](#exchange-api\/tag\/cards\/POST\/cards\/audit-status) with the\n  `request_id` until issuance is final.\n\n> Order matters: a cardholder must be clean on `requires_approval` first \u2014 otherwise `apply` \/ `topup`\n> can be blocked before issuance even starts.\n\n## Card statuses\n\n`status` (and, on `POST \/{id}\/info`, a machine-readable `status` + `status_label` + `can_*` flags) can be:\n\n| Status | Meaning |\n|---|---|\n| `ACTIVE` | Usable; spending and top-up allowed within limits. |\n| `INACTIVE` \/ `NEED_ACTIVATION` \/ `PENDING_ACTIVE` | Issued but needs activation. |\n| `LOCKED` \/ `LOCK` | Temporarily locked by the user; unlock via API. |\n| `SUSPENDED` | Blocked by platform policy (the unlock API does not apply). |\n| `CLOSED` | Permanently closed. |\n| `WAIT_AUDIT` \/ `CARD_REVIEWING` \/ `WAITING_FOR_APPROVAL` \/ `PENDING` | Under review \/ processing. |\n| `PASS_AUDIT` \/ `APPROVED` \/ `CARD_APPROVED` | Passed review; ready to activate. |\n| `INITIALIZED` \/ `CARD_INIT` | Record created; processing not finished. |\n| `FAIL_AUDIT` \/ `REJECTED` \/ `CARD_REJECT` | Rejected \u2014 the application cannot continue as-is. |\n\nWhile a card is pending\/under review, keep polling `audit-status`, and use `POST \/{id}\/info` when you\nneed the exact code and the `can_activate` \/ `can_lock` hints.\n\nCardholder `kyc_status`: `0` not set \u00b7 `1` waiting for audit \u00b7 `2` in audit \u00b7 `3` approved \u00b7 `4`\nrefused. A card can be issued once the cardholder is `3` (approved) and not `requires_approval`.\n\n## Error handling\n\nBusiness errors return `success: false` with an `error.code`; authentication, validation and rate\nlimits use standard HTTP statuses.\n\n| Code | HTTP | When |\n|---|---|---|\n| \u2014 | `401` | Missing or invalid Bearer token. |\n| \u2014 | `422` | Request validation failed (field errors in the body). |\n| \u2014 | `429` | Too many requests \u2014 retry later. |\n| `NOT_FOUND` | 404 | Cardholder, card or application not found. |\n| `WALLET_ERROR` | 400 | Currency not supported, or no wallet for it. |\n| `INSUFFICIENT_BALANCE` | 400 | Not enough wallet balance for the fee \/ top-up. |\n| `INVALID_PRODUCT` \/ `INVALID_CARD_PRODUCT` | 400 | Card product invalid or not configured. |\n| `PRODUCT_DISABLED` | 400 | Card product is turned off (coming soon). |\n| `CARD_PRODUCTS_NOT_CONFIGURED` | 503 | No card products configured. |\n| `CARDHOLDER_NOT_READY` | 422 | Cardholder is not linked to the issuer yet. |\n| `CARDHOLDER_PENDING_APPROVAL` | 400 | Cardholder still needs manual approval. |\n| `FORBIDDEN_COUNTRY` | 422 | Cardholder country is not eligible. |\n| `INVALID_CARD_STATUS` | 400 | Card is not in a valid state for this action. |\n| `CARD_NOT_READY` | 400 | Card is still initializing \u2014 refresh and retry. |\n| `INTERNAL_ERROR` | 500 | Unexpected failure \u2014 retry later or contact support. |\n"}]}