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:

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

---

Plan Management

Create a Plan

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:

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

Get Plan

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

Add Signature

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

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

Response:

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

Get Execution Status

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

Stream Execution Status (SSE)

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

Abort Execution

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

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

Response:

{
  "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

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

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:

{
  "success": true,
  "gasEstimate": 250000,
  "slippage": 0.5,
  "liquidityCheck": true,
  "warnings": []
}

---

Adapters

List Available Adapters

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

Response:

{
  "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

curl http://localhost:8080/health

Metrics (Prometheus)

curl http://localhost:8080/metrics

Liveness Check

curl http://localhost:8080/live

Readiness Check

curl http://localhost:8080/ready

---

Error Handling

All errors follow this format:

{
  "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:

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

# 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