asle/API_DOCUMENTATION.md

# ASLE API Documentation

## Base URL

- Development: `http://localhost:4000/api`
- Production: `https://api.asle.com/api`

## Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

```
Authorization: Bearer <token>
```

## REST API Endpoints

### Pools

#### GET /api/pools
List all liquidity pools.

**Response:**
```json
{
  "pools": [
    {
      "id": 1,
      "baseToken": "0x...",
      "quoteToken": "0x...",
      "baseReserve": "1000",
      "quoteReserve": "2000",
      "active": true
    }
  ]
}
```

#### GET /api/pools/:poolId
Get pool details.

**Parameters:**
- `poolId` (path): Pool ID

**Response:**
```json
{
  "pool": {
    "id": 1,
    "baseToken": "0x...",
    "quoteToken": "0x...",
    "baseReserve": "1000",
    "quoteReserve": "2000",
    "virtualBaseReserve": "5000",
    "virtualQuoteReserve": "10000",
    "k": "5000",
    "oraclePrice": "2000000000000000000",
    "active": true
  }
}
```

#### POST /api/pools
Create a new pool (requires authentication).

**Request Body:**
```json
{
  "baseToken": "0x...",
  "quoteToken": "0x...",
  "initialBaseReserve": "1000",
  "initialQuoteReserve": "2000",
  "virtualBaseReserve": "5000",
  "virtualQuoteReserve": "10000",
  "k": "5000",
  "oraclePrice": "2000000000000000000",
  "oracle": "0x..." // optional
}
```

### Vaults

#### GET /api/vaults
List all vaults.

#### GET /api/vaults/:vaultId
Get vault details.

#### POST /api/vaults
Create a new vault (requires authentication).

**Request Body:**
```json
{
  "asset": "0x...", // optional for multi-asset vaults
  "isMultiAsset": false
}
```

### Compliance

#### POST /api/compliance/kyc/verify
Verify KYC for a user (requires authentication).

**Request Body:**
```json
{
  "userAddress": "0x...",
  "provider": "default" // optional
}
```

#### POST /api/compliance/aml/verify
Verify AML for a user (requires authentication).

#### POST /api/compliance/ofac/check
Check OFAC sanctions (requires authentication).

#### GET /api/compliance/record/:userAddress
Get compliance record for a user.

### CCIP

#### GET /api/ccip/messages
List all CCIP messages.

#### GET /api/ccip/messages/:messageId
Get message details.

#### GET /api/ccip/chains/:chainId
Get messages for a specific chain.

#### POST /api/ccip/track
Track a new CCIP message (requires authentication).

### Monitoring

#### GET /api/monitoring/health
Get system health status.

**Response:**
```json
{
  "success": true,
  "health": {
    "status": "healthy",
    "components": {
      "contracts": { "status": "up", "lastCheck": 1234567890 },
      "backend": { "status": "up", "lastCheck": 1234567890 }
    },
    "alerts": [],
    "metrics": []
  }
}
```

#### GET /api/monitoring/alerts
Get system alerts (requires authentication).

**Query Parameters:**
- `type` (optional): Filter by alert type
- `severity` (optional): Filter by severity
- `resolved` (optional): Filter by resolution status

#### POST /api/monitoring/alerts
Create an alert (requires authentication).

#### GET /api/monitoring/metrics
Get system metrics.

**Query Parameters:**
- `name` (optional): Filter by metric name
- `from` (optional): Start timestamp
- `to` (optional): End timestamp

## GraphQL API

### Endpoint

`http://localhost:4000/graphql`

### Schema

```graphql
type Pool {
  id: ID!
  baseToken: String!
  quoteToken: String!
  baseReserve: String!
  quoteReserve: String!
  virtualBaseReserve: String
  virtualQuoteReserve: String
  k: String
  oraclePrice: String
  active: Boolean!
}

type Vault {
  id: ID!
  asset: String
  totalAssets: String!
  totalSupply: String!
  isMultiAsset: Boolean!
  active: Boolean!
}

type Query {
  pools: [Pool!]!
  pool(id: ID!): Pool
  vaults: [Vault!]!
  vault(id: ID!): Vault
}

type Mutation {
  createPool(
    baseToken: String!
    quoteToken: String!
    initialBaseReserve: String!
    initialQuoteReserve: String!
    virtualBaseReserve: String!
    virtualQuoteReserve: String!
    k: String!
    oraclePrice: String!
  ): Pool!
  
  createVault(
    asset: String
    isMultiAsset: Boolean!
  ): Vault!
}
```

### Example Queries

**Get all pools:**
```graphql
query {
  pools {
    id
    baseToken
    quoteToken
    baseReserve
    active
  }
}
```

**Create a pool:**
```graphql
mutation {
  createPool(
    baseToken: "0x..."
    quoteToken: "0x..."
    initialBaseReserve: "1000"
    initialQuoteReserve: "2000"
    virtualBaseReserve: "5000"
    virtualQuoteReserve: "10000"
    k: "5000"
    oraclePrice: "2000000000000000000"
  ) {
    id
    active
  }
}
```

## Rate Limiting

- General API: 100 requests per 15 minutes per IP
- Auth endpoints: 5 requests per 15 minutes per IP
- Strict endpoints: 10 requests per 15 minutes per IP

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

## Error Responses

All errors follow this format:

```json
{
  "error": "Error message",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

HTTP Status Codes:
- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `500` - Internal Server Error

## WebSocket Support

Real-time updates available via WebSocket:
- Pool state updates
- Vault balance changes
- System alerts
- Transaction confirmations

**Connection:** `ws://localhost:4000/ws`

## SDK Examples

### JavaScript/TypeScript

```typescript
import api from './lib/api';

// Get pools
const response = await api.get('/pools');
const pools = response.data.pools;

// Create pool
await api.post('/pools', {
  baseToken: '0x...',
  quoteToken: '0x...',
  // ...
});
```

### GraphQL Client

```typescript
import { ApolloClient, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'http://localhost:4000/graphql'
});

const GET_POOLS = gql`
  query {
    pools {
      id
      baseToken
      quoteToken
    }
  }
`;

const { data } = await client.query({ query: GET_POOLS });
```

## Versioning

API versioning via URL path:
- `/api/v1/pools`
- `/api/v2/pools` (future)

Current version: v1 (default)

## Support

For API support:
- Check documentation
- Review error messages
- Contact: api-support@asle.com