dbis_docs/gru_reserve_system/appendices/Appendix_B_API_Specifications.md

# APPENDIX B: API SPECIFICATIONS
## Complete API Documentation for GRU Reserve System

**Document Number:** DBIS-GRU-APP-B  
**Version:** 1.0  
**Date:** [Enter date in ISO 8601 format: YYYY-MM-DD]  
**Classification:** CONFIDENTIAL  
**Authority:** DBIS Technical Department

---

## PREAMBLE

This appendix provides complete API specifications for the GRU Reserve System, including REST API endpoints, request/response formats, authentication, and error handling.

---

## PART I: API OVERVIEW

### Section 1.1: API Architecture

**API Type:** RESTful API

**Base URL:** `https://api.dbis.org/v1/reserve`

**API Versioning:**
- Current version: v1
- Version specified in URL path
- Backward compatibility maintained for at least 2 versions

**Authentication:**
- OAuth 2.0 with JWT tokens
- API keys for service-to-service communication
- Certificate-based authentication for high-security operations

---

## PART II: RESERVE MANAGEMENT APIs

### Section 2.1: Get Reserve Status

**Endpoint:** `GET /reserve/status`

**Authentication:** Required (API key or OAuth token)

**Request:**
```
GET /v1/reserve/status
Headers:
  Authorization: Bearer {token}
  Accept: application/json
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "total_reserves": 34500000.00,
    "currency": "USD",
    "reserve_ratio": 1.15,
    "minimum_required": 30000000.00,
    "assets": [
      {
        "type": "XAU",
        "quantity": 10000.0,
        "unit": "oz",
        "value": 20000000.00,
        "weight": 1.0
      },
      {
        "type": "BTC",
        "quantity": 100.0,
        "unit": "BTC",
        "value": 5000000.00,
        "weight": 0.9
      }
    ],
    "liabilities": {
      "total": 30000000.00,
      "currency": "USD"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

**Error Responses:**
- 401 Unauthorized: Invalid or missing authentication
- 403 Forbidden: Insufficient permissions
- 500 Internal Server Error: Server error

---

### Section 2.2: Get Asset Details

**Endpoint:** `GET /reserve/assets/{asset_type}`

**Parameters:**
- `asset_type`: Asset type (XAU, BTC, ETH, etc.)

**Response:**
```json
{
  "status": "success",
  "data": {
    "asset_type": "XAU",
    "quantity": 10000.0,
    "unit": "oz",
    "current_price": 2000.00,
    "value": 20000000.00,
    "location": "allocated",
    "purity": 0.9999,
    "last_updated": "2024-01-15T10:30:00Z"
  }
}
```

---

## PART III: CONVERSION APIs

### Section 3.1: Request Conversion

**Endpoint:** `POST /reserve/convert`

**Request:**
```json
{
  "source_asset": "USD",
  "target_asset": "XAU",
  "amount": 100000.00,
  "source_unit": "USD",
  "target_unit": "oz"
}
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "conversion_id": "CONV-2024-001-12345",
    "source_asset": "USD",
    "target_asset": "XAU",
    "source_amount": 100000.00,
    "target_amount": 50.0,
    "conversion_rate": 2000.00,
    "fees": {
      "base_fee": 0.1,
      "slippage_fee": 0.0,
      "large_transaction_fee": 0.05,
      "total_fee": 0.15,
      "fee_amount": 0.075
    },
    "path": "direct",
    "estimated_settlement": "2024-01-15T10:35:00Z",
    "status": "pending"
  }
}
```

**Error Responses:**
- 400 Bad Request: Invalid request parameters
- 402 Payment Required: Insufficient reserves
- 429 Too Many Requests: Rate limit exceeded

---

### Section 3.2: Get Conversion Status

**Endpoint:** `GET /reserve/convert/{conversion_id}`

**Response:**
```json
{
  "status": "success",
  "data": {
    "conversion_id": "CONV-2024-001-12345",
    "status": "completed",
    "source_asset": "USD",
    "target_asset": "XAU",
    "source_amount": 100000.00,
    "target_amount": 50.0,
    "actual_rate": 2000.00,
    "fees": {
      "total_fee": 0.15,
      "fee_amount": 0.075
    },
    "settled_at": "2024-01-15T10:35:00Z",
    "transaction_hash": "0x1234..."
  }
}
```

---

## PART IV: BOND SYSTEM APIs

### Section 4.1: Issue Bonds

**Endpoint:** `POST /reserve/bonds/issue`

**Request:**
```json
{
  "amount": 1000000.00,
  "currency": "USD",
  "maturity_years": 5,
  "interest_rate": 0.03,
  "backing_assets": ["XAU"]
}
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "bond_id": "BOND-2024-001",
    "face_value": 1000000.00,
    "currency": "USD",
    "maturity_date": "2029-01-15",
    "interest_rate": 0.03,
    "issue_date": "2024-01-15",
    "backing_assets": ["XAU"],
    "backing_value": 1250000.00,
    "coverage_ratio": 1.25
  }
}
```

---

### Section 4.2: Redeem Bonds

**Endpoint:** `POST /reserve/bonds/{bond_id}/redeem`

**Request:**
```json
{
  "redemption_amount": 1000000.00,
  "redemption_date": "2024-01-15"
}
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "bond_id": "BOND-2024-001",
    "redemption_amount": 1000000.00,
    "accrued_interest": 25000.00,
    "total_redemption": 1025000.00,
    "redemption_date": "2024-01-15",
    "settlement_assets": ["XAU"],
    "settlement_amount": 512.5
  }
}
```

---

## PART V: AUTHENTICATION AND SECURITY

### Section 5.1: Authentication

**OAuth 2.0 Flow:**
1. Client requests authorization
2. User authorizes
3. Authorization server issues access token
4. Client uses access token for API requests
5. Token refresh as needed

**API Key Authentication:**
- API keys issued by DBIS
- Keys rotated every 90 days
- Keys stored securely (never in code)

**Certificate Authentication:**
- X.509 certificates for high-security operations
- Certificate validation required
- Mutual TLS (mTLS) for certificate-based authentication

---

### Section 5.2: Rate Limiting

**Rate Limits:**
- Standard API key: 100 requests per minute
- OAuth token: 1000 requests per minute
- Certificate-based: 10000 requests per minute

**Rate Limit Headers:**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000
```

---

## PART VI: ERROR HANDLING

### Section 6.1: Error Response Format

**Standard Error Response:**
```json
{
  "status": "error",
  "error": {
    "code": "RESERVE_INSUFFICIENT",
    "message": "Insufficient reserves for requested conversion",
    "details": {
      "required": 100000.00,
      "available": 50000.00
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "REQ-2024-001-12345"
  }
}
```

**Error Codes:**
- `AUTH_REQUIRED`: Authentication required
- `AUTH_INVALID`: Invalid authentication
- `PERMISSION_DENIED`: Insufficient permissions
- `INVALID_REQUEST`: Invalid request parameters
- `RESERVE_INSUFFICIENT`: Insufficient reserves
- `CONVERSION_FAILED`: Conversion failed
- `RATE_LIMIT_EXCEEDED`: Rate limit exceeded
- `SERVER_ERROR`: Internal server error

---

## PART VII: WEBHOOKS AND NOTIFICATIONS

### Section 7.1: Webhook Events

**Event Types:**
- `conversion.completed`: Conversion completed
- `conversion.failed`: Conversion failed
- `bond.issued`: Bond issued
- `bond.redeemed`: Bond redeemed
- `reserve.threshold`: Reserve threshold reached

**Webhook Payload:**
```json
{
  "event": "conversion.completed",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "conversion_id": "CONV-2024-001-12345",
    "status": "completed"
  }
}
```

---

## IMPLEMENTATION NOTES

- All APIs use HTTPS only (TLS 1.3)
- All requests and responses are JSON
- All timestamps in ISO 8601 format
- All monetary amounts in base currency (USD) unless specified
- API versioning in URL path
- Comprehensive error handling
- Rate limiting implemented
- Audit logging for all API calls

---

**END OF APPENDIX B**