CurrenciCombo/docs/API_USAGE_EXAMPLES.md

# API Usage Examples

This document provides practical examples for using the Orchestrator API.

---

## Authentication

All API requests require authentication via API key in the header:

```bash
curl -H "X-API-Key: your-api-key" \
     http://localhost:8080/api/plans
```

---

## Plan Management

### Create a Plan

```bash
curl -X POST http://localhost:8080/api/plans \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "creator": "user@example.com",
    "steps": [
      {
        "type": "borrow",
        "asset": "USDC",
        "amount": 1000,
        "from": "aave"
      },
      {
        "type": "swap",
        "asset": "USDC",
        "amount": 1000,
        "from": "USDC",
        "to": "ETH"
      }
    ],
    "maxRecursion": 3,
    "maxLTV": 0.6
  }'
```

**Response:**
```json
{
  "plan_id": "plan-12345",
  "plan_hash": "0xabc123...",
  "created_at": "2025-01-15T10:00:00Z"
}
```

### Get Plan

```bash
curl http://localhost:8080/api/plans/plan-12345 \
  -H "X-API-Key: your-api-key"
```

### Add Signature

```bash
curl -X POST http://localhost:8080/api/plans/plan-12345/signature \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "signature": "0xdef456...",
    "messageHash": "0x789abc...",
    "signerAddress": "0x1234567890abcdef..."
  }'
```

---

## Execution

### Execute Plan

```bash
curl -X POST http://localhost:8080/api/plans/plan-12345/execute \
  -H "X-API-Key: your-api-key"
```

**Response:**
```json
{
  "executionId": "exec-67890",
  "status": "pending",
  "startedAt": "2025-01-15T10:05:00Z"
}
```

### Get Execution Status

```bash
curl http://localhost:8080/api/plans/plan-12345/status?executionId=exec-67890 \
  -H "X-API-Key: your-api-key"
```

### Stream Execution Status (SSE)

```bash
curl -N http://localhost:8080/api/plans/plan-12345/status/stream \
  -H "X-API-Key: your-api-key"
```

### Abort Execution

```bash
curl -X POST http://localhost:8080/api/plans/plan-12345/abort?executionId=exec-67890 \
  -H "X-API-Key: your-api-key"
```

---

## Compliance

### Check Compliance Status

```bash
curl http://localhost:8080/api/compliance/status \
  -H "X-API-Key: your-api-key"
```

**Response:**
```json
{
  "lei": "5493000JXH2RCDW0KV24",
  "did": "did:web:example.com:user123",
  "kyc": {
    "level": 2,
    "verified": true,
    "expiresAt": "2026-01-15T00:00:00Z"
  },
  "aml": {
    "passed": true,
    "lastCheck": "2025-01-15T09:00:00Z",
    "riskLevel": "low"
  },
  "valid": true
}
```

### Validate Plan Compliance

```bash
curl -X POST http://localhost:8080/api/compliance/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "steps": [
      {"type": "pay", "amount": 1000}
    ]
  }'
```

---

## Simulation

### Simulate Plan Execution

```bash
curl -X POST http://localhost:8080/api/plans/plan-12345/simulate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "includeGasEstimate": true,
    "includeSlippageAnalysis": true,
    "includeLiquidityCheck": true
  }'
```

**Response:**
```json
{
  "success": true,
  "gasEstimate": 250000,
  "slippage": 0.5,
  "liquidityCheck": true,
  "warnings": []
}
```

---

## Adapters

### List Available Adapters

```bash
curl http://localhost:8080/api/adapters \
  -H "X-API-Key: your-api-key"
```

**Response:**
```json
{
  "adapters": [
    {
      "id": "uniswap-v3",
      "name": "Uniswap V3",
      "type": "swap",
      "whitelisted": true,
      "status": "active"
    },
    {
      "id": "aave-v3",
      "name": "Aave V3",
      "type": "borrow",
      "whitelisted": true,
      "status": "active"
    }
  ]
}
```

---

## Health & Monitoring

### Health Check

```bash
curl http://localhost:8080/health
```

### Metrics (Prometheus)

```bash
curl http://localhost:8080/metrics
```

### Liveness Check

```bash
curl http://localhost:8080/live
```

### Readiness Check

```bash
curl http://localhost:8080/ready
```

---

## Error Handling

All errors follow this format:

```json
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid plan structure",
  "details": {
    "field": "steps",
    "issue": "Steps array cannot be empty"
  },
  "requestId": "req-12345"
}
```

### Common Error Types

- `VALIDATION_ERROR` (400): Invalid input data
- `NOT_FOUND_ERROR` (404): Resource not found
- `AUTHENTICATION_ERROR` (401): Missing or invalid API key
- `EXTERNAL_SERVICE_ERROR` (502): External service failure
- `SYSTEM_ERROR` (500): Internal server error

---

## Rate Limiting

API requests are rate-limited:
- **Default**: 100 requests per minute per API key
- **Burst**: 20 requests per second

Rate limit headers:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000
```

---

## Webhooks

Register a webhook for plan status updates:

```bash
curl -X POST http://localhost:8080/api/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "secret": "webhook-secret",
    "events": ["plan.status", "plan.executed"]
  }'
```

---

## Complete Example: Full Flow

```bash
# 1. Create plan
PLAN_ID=$(curl -X POST http://localhost:8080/api/plans \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"creator":"user@example.com","steps":[...]}' \
  | jq -r '.plan_id')

# 2. Add signature
curl -X POST http://localhost:8080/api/plans/$PLAN_ID/signature \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"signature":"0x...","messageHash":"0x...","signerAddress":"0x..."}'

# 3. Execute
EXEC_ID=$(curl -X POST http://localhost:8080/api/plans/$PLAN_ID/execute \
  -H "X-API-Key: your-api-key" \
  | jq -r '.executionId')

# 4. Monitor status
curl -N http://localhost:8080/api/plans/$PLAN_ID/status/stream \
  -H "X-API-Key: your-api-key"

# 5. Get receipts
curl http://localhost:8080/api/receipts/$PLAN_ID \
  -H "X-API-Key: your-api-key"
```

---

**Last Updated**: 2025-01-15