# Kurrency API (v1.0.0) — Complete API Reference

High-performance, edge-cached Fiat and Crypto currency conversion API.

**Contact:** [support@kurrency.dev](mailto:support@kurrency.dev)

---

## Base URLs

- **`https://api.kurrency.dev`** — Production API Server

---

## Authentication

### JwtAuth

- **Type:** http bearer
- **Format:** JWT

Provide your JWT session token obtained from `/auth/login`

### ApiKeyAuth

- **Type:** http bearer

Provide your API Key as a Bearer token (e.g., `Authorization: Bearer sk_...`)

### ApiKeyQuery

- **Type:** apiKey
- **In:** query

Alternatively, provide your API Key via the `api_key` query string parameter.

---

## Rates & Conversion

Core currency conversion and rate aggregation endpoints

### GET /v1/rates

**Get all current exchange rates**

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.

**Authentication:** ApiKeyAuth, ApiKeyQuery

**Responses:**

#### ✅ 200 — Successfully retrieved rates

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `updatedAt` | integer | No | Unix timestamp (in milliseconds) of the last rate aggregation |
| `fiat` | object | No | Dictionary mapping Fiat currency codes (e.g., 'EUR') to their value in USD |
| `crypto` | object | No | Dictionary mapping Crypto ticker symbols (e.g., 'BTC') to their value in USD |

#### ❌ 401 — Missing or invalid API Key

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |

#### ❌ 503 — Rates currently unavailable or caching

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |


### GET /v1/convert

**Convert between two currencies**

Calculates the exchange rate between any two supported fiat or cryptocurrencies.

**Authentication:** ApiKeyAuth, ApiKeyQuery

**Query Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | Yes | The source currency code (e.g., USD, EUR, BTC) |
| `to` | string | Yes | The target currency code (e.g., GBP, JPY, ETH) |
| `from_type` | string (fiat|crypto) | No | Force the source currency type if there is a conflict (e.g., fiat or crypto) |
| `to_type` | string (fiat|crypto) | No | Force the target currency type if there is a conflict (e.g., fiat or crypto) |

**Responses:**

#### ✅ 200 — Successful conversion rate calculation

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from` | string | No |  |
| `to` | string | No |  |
| `rate` | number | No | The exact calculated exchange rate multiplier from the source to target currency |
| `updatedAt` | integer | No | Unix timestamp (in milliseconds) of the rates used for this calculation |

#### ❌ 400 — Missing required parameters

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |

#### ❌ 401 — Missing or invalid API Key

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |

#### ❌ 404 — Currency not found

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |

#### ❌ 503 — Rates currently unavailable or caching

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |


---

## Account Management

Public endpoints for user registration and dashboard authentication

### POST /auth/register

**Register a new developer account**

Creates a new developer account. The account must be verified by an administrator before API keys can be generated.

**Request Body (required):**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string(email) | Yes |  |
| `password` | string | Yes |  |

**Responses:**

#### ✅ 200 — Registration successful

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |
| `message` | string | No |  |

#### ❌ 400 — Invalid input or email already exists

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |


### POST /auth/login

**Login to developer dashboard**

Authenticates a developer and returns a JWT token for dashboard access.

**Request Body (required):**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string(email) | Yes |  |
| `password` | string | Yes |  |

**Responses:**

#### ✅ 200 — Login successful

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `token` | string | No | JWT Bearer Token |
| `user` | object | No |  |

#### ❌ 401 — Invalid credentials

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |


---

## API Keys

Endpoints for managing your developer API keys

### GET /user/keys

**List your API keys**

Retrieves all API keys associated with your account.

**Authentication:** JwtAuth

**Responses:**

#### ✅ 200 — Successfully retrieved API keys

Content-Type: `application/json`

Array of:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No |  |
| `api_key` | string | No |  |
| `name` | string | No |  |
| `is_active` | integer (0|1) | No |  |
| `created_at` | string(date-time) | No |  |

#### ❌ 401 — Unauthorized (Missing or invalid JWT)

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |


### POST /user/keys

**Create a new API key**

Generates a new secure API key. Your account must be verified by an admin to use this endpoint.

**Authentication:** JwtAuth

**Request Body (required):**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | A descriptive name for the API key |

**Responses:**

#### ✅ 200 — Successfully generated API key

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |
| `api_key` | string | No |  |

#### ❌ 401 — Unauthorized (Missing or invalid JWT)

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |

#### ❌ 403 — Account not verified by admin

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |


### DELETE /user/keys/{id}

**Revoke an API key**

Permanently revokes and deletes the specified API key.

**Authentication:** JwtAuth

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | The unique ID of the API key to revoke |

**Responses:**

#### ✅ 200 — Successfully revoked API key

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No |  |

#### ❌ 401 — Unauthorized (Missing or invalid JWT)

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | string | No |  |
| `details` | string | No |  |


---

*Generated by [CleanDocs](https://cleandocs.dev) — AI-readable API documentation*