{"openapi":"3.0.3","info":{"title":"SmartCheq API","description":"SmartCheq CBDC Platform API for trade claims, corridors, institutions, and settlements.\n\n## Authentication\n\nThis API uses OAuth 2.0 Client Credentials flow:\n\n1. **Get Access Token**\n   ```\n   POST /oauth/token\n   Content-Type: application/x-www-form-urlencoded\n   \n   grant_type=client_credentials\u0026client_id=YOUR_CLIENT_ID\u0026client_secret=YOUR_CLIENT_SECRET\n   ```\n\n2. **Use Token in Requests**\n   ```\n   Authorization: Bearer YOUR_ACCESS_TOKEN\n   ```\n\nTokens expire after 24 hours (86400 seconds).","version":"2.0.0","contact":{"name":"SmartCheq API Support","email":"info@smartcheq.com","url":"https://www.smartcheq.com"},"license":{"name":"Proprietary","url":"https://www.smartcheq.com/terms_of_use"}},"servers":[{"url":"https://api.smartcheq.com","description":"Production API"},{"url":"http://localhost:3000","description":"Development"}],"tags":[{"name":"Health","description":"API health and status endpoints"},{"name":"Trade Claims","description":"Submit and manage trade claims for settlement"},{"name":"Corridors","description":"Trade corridor configuration and limits"},{"name":"Institutions","description":"Participating financial institutions"},{"name":"Audit Logs","description":"System audit trail and compliance logs"},{"name":"OAuth Applications","description":"API key management for OAuth applications"}],"paths":{"/api/v2/health":{"get":{"tags":["Health"],"summary":"Check API health","description":"Returns the health status of the API","operationId":"getHealth","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"service":{"type":"string","example":"smartcheq"},"version":{"type":"string","example":"v2"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v2/trade_claims":{"get":{"tags":["Trade Claims"],"summary":"List trade claims","description":"Retrieve a paginated list of trade claims with optional filters","operationId":"listTradeClaims","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PerPageParam"},{"name":"status","in":"query","description":"Filter by claim status","schema":{"type":"string","enum":["pending","approved","rejected","settled","pre_cleared"]}},{"name":"corridor_code","in":"query","description":"Filter by corridor code","schema":{"type":"string","example":"NGA-GHA"}},{"name":"from_date","in":"query","description":"Filter claims from this date (ISO 8601)","schema":{"type":"string","format":"date"}},{"name":"to_date","in":"query","description":"Filter claims up to this date (ISO 8601)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"List of trade claims","content":{"application/json":{"schema":{"type":"object","properties":{"trade_claims":{"type":"array","items":{"$ref":"#/components/schemas/TradeClaim"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Trade Claims"],"summary":"Create a trade claim","description":"Submit a new trade claim for processing","operationId":"createTradeClaim","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeClaimCreate"}}}},"responses":{"201":{"description":"Trade claim created","content":{"application/json":{"schema":{"type":"object","properties":{"trade_claim":{"$ref":"#/components/schemas/TradeClaim"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/api/v2/trade_claims/{id}":{"get":{"tags":["Trade Claims"],"summary":"Get a trade claim","description":"Retrieve details of a specific trade claim","operationId":"getTradeClaim","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Trade claim ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Trade claim details","content":{"application/json":{"schema":{"type":"object","properties":{"trade_claim":{"$ref":"#/components/schemas/TradeClaim"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v2/corridors":{"get":{"tags":["Corridors"],"summary":"List corridors","description":"Retrieve all configured trade corridors","operationId":"listCorridors","responses":{"200":{"description":"List of corridors","content":{"application/json":{"schema":{"type":"object","properties":{"corridors":{"type":"array","items":{"$ref":"#/components/schemas/Corridor"}}}}}}}}}},"/api/v2/corridors/{id}":{"get":{"tags":["Corridors"],"summary":"Get a corridor","description":"Retrieve details of a specific corridor","operationId":"getCorridor","parameters":[{"name":"id","in":"path","required":true,"description":"Corridor ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Corridor details","content":{"application/json":{"schema":{"type":"object","properties":{"corridor":{"$ref":"#/components/schemas/Corridor"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v2/institutions":{"get":{"tags":["Institutions"],"summary":"List institutions","description":"Retrieve all participating financial institutions","operationId":"listInstitutions","responses":{"200":{"description":"List of institutions","content":{"application/json":{"schema":{"type":"object","properties":{"institutions":{"type":"array","items":{"$ref":"#/components/schemas/Institution"}}}}}}}}}},"/api/v2/institutions/{id}":{"get":{"tags":["Institutions"],"summary":"Get an institution","description":"Retrieve details of a specific institution","operationId":"getInstitution","parameters":[{"name":"id","in":"path","required":true,"description":"Institution ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Institution details","content":{"application/json":{"schema":{"type":"object","properties":{"institution":{"$ref":"#/components/schemas/Institution"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/audit_logs":{"get":{"tags":["Audit Logs"],"summary":"List audit logs","description":"Retrieve system audit logs with optional filters","operationId":"listAuditLogs","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PerPageParam"},{"name":"type","in":"query","description":"Filter by auditable type","schema":{"type":"string","example":"TradeClaim"}},{"name":"action_filter","in":"query","description":"Filter by action","schema":{"type":"string","enum":["created","approved","rejected","pre_cleared","pending_review","liquidity_locked"]}},{"name":"from","in":"query","description":"Filter logs from this date (ISO 8601)","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Filter logs up to this date (ISO 8601)","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"List of audit logs","content":{"application/json":{"schema":{"type":"object","properties":{"audit_logs":{"type":"array","items":{"$ref":"#/components/schemas/AuditLog"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}}},"/api/v2/oauth_applications":{"get":{"tags":["OAuth Applications"],"summary":"List OAuth applications","description":"Retrieve all registered OAuth applications (API keys)","operationId":"listOauthApplications","responses":{"200":{"description":"List of OAuth applications","content":{"application/json":{"schema":{"type":"object","properties":{"applications":{"type":"array","items":{"$ref":"#/components/schemas/OauthApplication"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"active":{"type":"integer"}}}}}}}}}},"post":{"tags":["OAuth Applications"],"summary":"Create OAuth application","description":"Register a new OAuth application and receive client credentials","operationId":"createOauthApplication","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["application"],"properties":{"application":{"type":"object","required":["name","redirect_uri"],"properties":{"name":{"type":"string","example":"Partner Bank API"},"redirect_uri":{"type":"string","example":"http://localhost"},"scopes":{"type":"string","example":"read write"}}}}}}}},"responses":{"201":{"description":"Application created with credentials","content":{"application/json":{"schema":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/OauthApplication"},"credentials":{"type":"object","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"warning":{"type":"string"}}}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/api/v2/oauth_applications/stats":{"get":{"tags":["OAuth Applications"],"summary":"Get API usage statistics","description":"Retrieve statistics about API usage and tokens","operationId":"getOauthStats","responses":{"200":{"description":"API statistics","content":{"application/json":{"schema":{"type":"object","properties":{"total_applications":{"type":"integer"},"active_tokens":{"type":"integer"},"tokens_expiring_soon":{"type":"integer"},"tokens_created_today":{"type":"integer"},"requests_today":{"type":"integer"},"rate_limit_percentage":{"type":"integer"}}}}}}}}},"/api/v2/oauth_applications/{id}":{"get":{"tags":["OAuth Applications"],"summary":"Get OAuth application details","description":"Retrieve details of a specific OAuth application including recent tokens","operationId":"getOauthApplication","parameters":[{"name":"id","in":"path","required":true,"description":"Application ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Application details","content":{"application/json":{"schema":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/OauthApplicationDetail"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["OAuth Applications"],"summary":"Delete OAuth application","description":"Delete an OAuth application and revoke all its tokens","operationId":"deleteOauthApplication","parameters":[{"name":"id","in":"path","required":true,"description":"Application ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Application deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Application revoked successfully"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v2/oauth_applications/{id}/regenerate":{"post":{"tags":["OAuth Applications"],"summary":"Regenerate client secret","description":"Generate a new client secret for an OAuth application","operationId":"regenerateOauthSecret","parameters":[{"name":"id","in":"path","required":true,"description":"Application ID","schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"revoke_tokens":{"type":"boolean","description":"Whether to revoke existing access tokens","default":false}}}}}},"responses":{"200":{"description":"New credentials generated","content":{"application/json":{"schema":{"type":"object","properties":{"application":{"$ref":"#/components/schemas/OauthApplication"},"credentials":{"type":"object","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"warning":{"type":"string"}}}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/oauth/token":{"post":{"tags":["Health"],"summary":"Get access token","description":"Exchange client credentials for an access token","operationId":"getAccessToken","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"],"example":"client_credentials"},"client_id":{"type":"string"},"client_secret":{"type":"string"}}}}}},"responses":{"200":{"description":"Access token issued","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer","example":86400},"created_at":{"type":"integer"}}}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"invalid_client"},"error_description":{"type":"string"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer Token"}},"parameters":{"PageParam":{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","default":1,"minimum":1}},"PerPageParam":{"name":"per_page","in":"query","description":"Items per page","schema":{"type":"integer","default":50,"minimum":1,"maximum":200}}},"responses":{"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string","example":"Invalid or expired token"}}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string","example":"Resource not found"}}}}}},"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"bad_request"},"message":{"type":"string"}}}}}},"UnprocessableEntity":{"description":"Validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"validation_failed"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}}}}}}},"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}},"TradeClaim":{"type":"object","properties":{"id":{"type":"integer"},"claim_reference":{"type":"string","example":"TC-2026-00001"},"source_country":{"type":"string","example":"NGA"},"target_country":{"type":"string","example":"GHA"},"source_currency":{"type":"string","example":"NGN"},"target_currency":{"type":"string","example":"GHS"},"amount":{"type":"number","example":1000000.0},"status":{"type":"string","enum":["pending","approved","rejected","settled","pre_cleared"]},"institution_id":{"type":"integer"},"corridor_code":{"type":"string","example":"NGA-GHA"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TradeClaimCreate":{"type":"object","required":["source_country","target_country","amount","institution_id"],"properties":{"source_country":{"type":"string","example":"NGA"},"target_country":{"type":"string","example":"GHA"},"source_currency":{"type":"string","example":"NGN"},"amount":{"type":"number","example":1000000.0},"institution_id":{"type":"integer"},"reference":{"type":"string","description":"External reference number"},"notes":{"type":"string"}}},"Corridor":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string","example":"NGA-GHA"},"source_country":{"type":"string","example":"NGA"},"target_country":{"type":"string","example":"GHA"},"daily_limit":{"type":"number","example":500000000},"per_tx_limit":{"type":"number","example":5000000},"monthly_limit":{"type":"number","example":15000000000},"high_risk":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Institution":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","example":"First Bank of Nigeria"},"swift_code":{"type":"string","example":"FBNINGLA"},"country":{"type":"string","example":"Nigeria"},"country_code":{"type":"string","example":"NGA"},"branch":{"type":"string"},"city":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AuditLog":{"type":"object","properties":{"id":{"type":"integer"},"auditable_type":{"type":"string","example":"TradeClaim"},"auditable_id":{"type":"integer"},"action":{"type":"string","example":"approved"},"notes":{"type":"string"},"user_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"OauthApplication":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","example":"Partner Bank API"},"uid":{"type":"string","description":"Masked client ID"},"uid_full":{"type":"string","description":"Full client ID"},"scopes":{"type":"string"},"confidential":{"type":"boolean"},"redirect_uri":{"type":"string"},"active_tokens_count":{"type":"integer"},"total_tokens_count":{"type":"integer"},"last_token_created":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"OauthApplicationDetail":{"allOf":[{"$ref":"#/components/schemas/OauthApplication"},{"type":"object","properties":{"recent_tokens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"token_preview":{"type":"string","example":"TmrAOTVS...3-A"},"scopes":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"expired":{"type":"boolean"},"revoked":{"type":"boolean"}}}}}}]}}}}