{ "openapi": "3.0.3", "info": { "title": "Kurrency API", "description": "High-performance, edge-cached Fiat and Crypto currency conversion API.", "version": "1.0.0", "contact": { "email": "support@kurrency.dev" } }, "servers": [ { "url": "https://api.kurrency.dev", "description": "Production API Server" } ], "tags": [ { "name": "Rates & Conversion", "description": "Core currency conversion and rate aggregation endpoints" }, { "name": "Account Management", "description": "Public endpoints for user registration and dashboard authentication" }, { "name": "API Keys", "description": "Endpoints for managing your developer API keys" } ], "paths": { "/v1/rates": { "get": { "tags": ["Rates & Conversion"], "summary": "Get all current exchange rates", "description": "Retrieves the latest aggregated exchange rates for both fiat and cryptocurrencies relative to USD. Served from our global cache network closest to each client for sub-10ms latency.", "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ], "responses": { "200": { "description": "Successfully retrieved rates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatesResponse" } } } }, "401": { "description": "Missing or invalid API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Rates currently unavailable or caching", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/convert": { "get": { "tags": ["Rates & Conversion"], "summary": "Convert between two currencies", "description": "Calculates the exchange rate between any two supported fiat or cryptocurrencies.", "security": [ { "ApiKeyAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "The source currency code (e.g., USD, EUR, BTC)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": true, "description": "The target currency code (e.g., GBP, JPY, ETH)", "schema": { "type": "string" } }, { "name": "from_type", "in": "query", "required": false, "description": "Force the source currency type if there is a conflict (e.g., fiat or crypto)", "schema": { "type": "string", "enum": ["fiat", "crypto"] } }, { "name": "to_type", "in": "query", "required": false, "description": "Force the target currency type if there is a conflict (e.g., fiat or crypto)", "schema": { "type": "string", "enum": ["fiat", "crypto"] } } ], "responses": { "200": { "description": "Successful conversion rate calculation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResponse" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Rates currently unavailable or caching", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/register": { "post": { "tags": ["Account Management"], "summary": "Register a new developer account", "description": "Creates a new developer account. The account must be verified by an administrator before API keys can be generated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 6 } } } } } }, "responses": { "200": { "description": "Registration successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid input or email already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/login": { "post": { "tags": ["Account Management"], "summary": "Login to developer dashboard", "description": "Authenticates a developer and returns a JWT token for dashboard access.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "JWT Bearer Token" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "is_verified": { "type": "integer", "enum": [0, 1] } } } } } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/user/keys": { "get": { "tags": ["API Keys"], "summary": "List your API keys", "description": "Retrieves all API keys associated with your account.", "security": [ { "JwtAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved API keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "401": { "description": "Unauthorized (Missing or invalid JWT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": ["API Keys"], "summary": "Create a new API key", "description": "Generates a new secure API key. Your account must be verified by an admin to use this endpoint.", "security": [ { "JwtAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "A descriptive name for the API key" } } } } } }, "responses": { "200": { "description": "Successfully generated API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "api_key": { "type": "string" } } } } } }, "401": { "description": "Unauthorized (Missing or invalid JWT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Account not verified by admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/user/keys/{id}": { "delete": { "tags": ["API Keys"], "summary": "Revoke an API key", "description": "Permanently revokes and deletes the specified API key.", "security": [ { "JwtAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique ID of the API key to revoke", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully revoked API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized (Missing or invalid JWT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "JwtAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Provide your JWT session token obtained from `/auth/login`" }, "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Provide your API Key as a Bearer token (e.g., `Authorization: Bearer sk_...`)" }, "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "Alternatively, provide your API Key via the `api_key` query string parameter." } }, "schemas": { "RatesResponse": { "type": "object", "properties": { "updatedAt": { "type": "integer", "description": "Unix timestamp (in milliseconds) of the last rate aggregation" }, "fiat": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Dictionary mapping Fiat currency codes (e.g., 'EUR') to their value in USD" }, "crypto": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Dictionary mapping Crypto ticker symbols (e.g., 'BTC') to their value in USD" } } }, "ConvertResponse": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "rate": { "type": "number", "description": "The exact calculated exchange rate multiplier from the source to target currency" }, "updatedAt": { "type": "integer", "description": "Unix timestamp (in milliseconds) of the rates used for this calculation" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "api_key": { "type": "string" }, "name": { "type": "string" }, "is_active": { "type": "integer", "enum": [0, 1] }, "created_at": { "type": "string", "format": "date-time" } } } } } }