Risk API

Check risk limits, validate orders before submission, and monitor risk exposure.

Endpoints

Method	Endpoint	Description
GET /api/sdk/risk/limits	Get configured risk limits
POST /api/sdk/risk/pre-trade-check	Validate order against limits
GET /api/sdk/risk/exposure	Get current risk exposure
GET /api/sdk/risk/exposure/:asset	Get exposure for specific asset
GET /api/sdk/risk/utilization	Get limit utilization summary
GET /api/sdk/risk/max-quantity	Get maximum order quantity
GET /api/sdk/risk/metrics	Get comprehensive risk metrics
POST /api/sdk/risk/simulate	Simulate order impact

Get Risk Limits

Get your configured risk limits.

GET /api/sdk/risk/limits

Required Scope: READ

Example Request

curl -X GET https://api.zenotc.com/api/sdk/risk/limits \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

limits = api_request("GET", "/api/sdk/risk/limits")

Response

{
  "limits": {
    "maxOrderSize": {
      "BTC": 10.0,
      "ETH": 100.0,
      "default": 50000.0
    },
    "maxOrderValue": 500000.00,
    "maxDailyVolume": 5000000.00,
    "maxOpenOrders": 100,
    "maxOpenOrdersPerAsset": 20,
    "maxExposure": 10000000.00,
    "maxExposurePerAsset": {
      "BTC": 2000000.00,
      "ETH": 1000000.00,
      "default": 500000.00
    },
    "maxLeverage": 1.0,
    "minOrderSize": {
      "BTC": 0.001,
      "ETH": 0.01,
      "default": 1.0
    }
  }
}

Limit Types

Limit	Description
`maxOrderSize`	Maximum quantity per order
`maxOrderValue`	Maximum USD value per order
`maxDailyVolume`	Maximum daily trading volume (USD)
`maxOpenOrders`	Maximum number of open orders
`maxOpenOrdersPerAsset`	Maximum open orders per asset
`maxExposure`	Maximum total portfolio exposure
`maxExposurePerAsset`	Maximum exposure per asset
`maxLeverage`	Maximum portfolio leverage
`minOrderSize`	Minimum quantity per order

Pre-Trade Check

Validate an order against risk limits before submission. Use this to check if an order would be accepted.

POST /api/sdk/risk/pre-trade-check

Required Scope: TRADE

Request Body

Parameter	Type	Required	Description
`side`	string	Yes	`buy` or `sell`
`asset`	string	Yes	Asset symbol
`quantity`	number	Yes	Order quantity
`price`	number	Yes	Order price

Example Request

curl -X POST https://api.zenotc.com/api/sdk/risk/pre-trade-check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature" \
  -d '{
    "side": "buy",
    "asset": "BTC",
    "quantity": 5.0,
    "price": 50000.00
  }'

check = api_request("POST", "/api/sdk/risk/pre-trade-check", {
    "side": "buy",
    "asset": "BTC",
    "quantity": 5.0,
    "price": 50000.00
})

Response (Approved)

{
  "approved": true,
  "orderValue": 250000.00,
  "checks": {
    "orderSize": {
      "passed": true,
      "limit": 10.0,
      "value": 5.0,
      "message": "Order size within limit"
    },
    "orderValue": {
      "passed": true,
      "limit": 500000.00,
      "value": 250000.00,
      "message": "Order value within limit"
    },
    "exposure": {
      "passed": true,
      "limit": 10000000.00,
      "currentValue": 775000.00,
      "afterValue": 1025000.00,
      "message": "Exposure within limit"
    },
    "assetExposure": {
      "passed": true,
      "limit": 2000000.00,
      "currentValue": 525000.00,
      "afterValue": 775000.00,
      "message": "Asset exposure within limit"
    },
    "availableBalance": {
      "passed": true,
      "required": 250000.00,
      "available": 300000.00,
      "message": "Sufficient balance"
    },
    "dailyVolume": {
      "passed": true,
      "limit": 5000000.00,
      "currentValue": 350000.00,
      "afterValue": 600000.00,
      "message": "Daily volume within limit"
    }
  },
  "warnings": []
}

Response (Rejected)

{
  "approved": false,
  "orderValue": 500000.00,
  "checks": {
    "orderSize": {
      "passed": false,
      "limit": 10.0,
      "value": 15.0,
      "message": "Order size exceeds limit"
    },
    "availableBalance": {
      "passed": false,
      "required": 500000.00,
      "available": 300000.00,
      "message": "Insufficient balance"
    }
  },
  "warnings": [],
  "rejectionReasons": [
    "Order size 15.0 exceeds maximum 10.0 for BTC",
    "Insufficient balance: required 500000.00, available 300000.00"
  ]
}

Get Risk Exposure

Get current portfolio risk exposure.

GET /api/sdk/risk/exposure

Required Scope: READ

Example Request

curl -X GET https://api.zenotc.com/api/sdk/risk/exposure \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

Response

{
  "totalExposure": 875000.00,
  "netExposure": 775000.00,
  "grossExposure": 875000.00,
  "longExposure": 775000.00,
  "shortExposure": 0,
  "cashBalance": 100000.00,
  "portfolioValue": 875000.00,
  "leverage": 0.89,
  "utilizationPercent": 8.75,
  "maxExposure": 10000000.00,
  "availableExposure": 9125000.00,
  "byAsset": [
    {
      "asset": "BTC",
      "exposure": 525000.00,
      "exposurePercent": 60.0,
      "limit": 2000000.00,
      "utilizationPercent": 26.25
    },
    {
      "asset": "ETH",
      "exposure": 250000.00,
      "exposurePercent": 28.6,
      "limit": 1000000.00,
      "utilizationPercent": 25.0
    }
  ]
}

Get Asset Risk Exposure

Get risk exposure for a specific asset.

GET /api/sdk/risk/exposure/:asset

Required Scope: READ

Path Parameters

Parameter	Type	Description
`asset`	string	Asset symbol

Example Request

curl -X GET https://api.zenotc.com/api/sdk/risk/exposure/BTC \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

Response

{
  "asset": "BTC",
  "exposure": 525000.00,
  "exposurePercent": 60.0,
  "limit": 2000000.00,
  "utilizationPercent": 26.25,
  "availableExposure": 1475000.00,
  "position": {
    "quantity": 10.5,
    "averagePrice": 50000.00,
    "currentPrice": 50000.00
  },
  "openOrders": {
    "buyQuantity": 2.5,
    "buyValue": 125000.00,
    "sellQuantity": 0,
    "sellValue": 0
  }
}

Get Limit Utilization

Get a summary of how much of each limit is being used.

GET /api/sdk/risk/utilization

Required Scope: READ

Example Request

curl -X GET https://api.zenotc.com/api/sdk/risk/utilization \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

Response

{
  "utilization": {
    "exposure": {
      "used": 875000.00,
      "limit": 10000000.00,
      "available": 9125000.00,
      "percent": 8.75
    },
    "dailyVolume": {
      "used": 350000.00,
      "limit": 5000000.00,
      "available": 4650000.00,
      "percent": 7.0
    },
    "openOrders": {
      "used": 5,
      "limit": 100,
      "available": 95,
      "percent": 5.0
    }
  },
  "byAsset": {
    "BTC": {
      "exposure": {
        "used": 525000.00,
        "limit": 2000000.00,
        "percent": 26.25
      },
      "openOrders": {
        "used": 3,
        "limit": 20,
        "percent": 15.0
      }
    },
    "ETH": {
      "exposure": {
        "used": 250000.00,
        "limit": 1000000.00,
        "percent": 25.0
      },
      "openOrders": {
        "used": 2,
        "limit": 20,
        "percent": 10.0
      }
    }
  },
  "breachedLimits": []
}

Get Max Quantity

Calculate the maximum quantity you can order given current limits and balances.

GET /api/sdk/risk/max-quantity

Required Scope: READ

Query Parameters

Parameter	Type	Required	Description
`side`	string	Yes	`buy` or `sell`
`asset`	string	Yes	Asset symbol
`price`	number	Yes	Order price

Example Request

curl -X GET "https://api.zenotc.com/api/sdk/risk/max-quantity?side=buy&asset=BTC&price=50000" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

max_qty = api_request("GET", "/api/sdk/risk/max-quantity?side=buy&asset=BTC&price=50000")

Response

{
  "side": "buy",
  "asset": "BTC",
  "price": 50000.00,
  "maxQuantity": 6.0,
  "limitingFactor": "available_balance",
  "details": {
    "byBalance": {
      "quantity": 6.0,
      "availableBalance": 300000.00
    },
    "byOrderSizeLimit": {
      "quantity": 10.0,
      "limit": 10.0
    },
    "byExposureLimit": {
      "quantity": 182.5,
      "availableExposure": 9125000.00
    },
    "byAssetExposureLimit": {
      "quantity": 29.5,
      "availableExposure": 1475000.00
    }
  }
}

Limiting Factors

Factor	Description
`available_balance`	Limited by available cash/asset balance
`order_size_limit`	Limited by max order size
`exposure_limit`	Limited by total exposure limit
`asset_exposure_limit`	Limited by per-asset exposure limit
`daily_volume_limit`	Limited by daily volume limit

Get Risk Metrics

Get comprehensive risk metrics for your portfolio.

GET /api/sdk/risk/metrics

Required Scope: READ

Example Request

curl -X GET https://api.zenotc.com/api/sdk/risk/metrics \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

Response

{
  "portfolioValue": 875000.00,
  "cashBalance": 100000.00,
  "positionsValue": 775000.00,
  "leverage": 0.89,
  "concentration": {
    "topAsset": "BTC",
    "topAssetWeight": 60.0,
    "herfindahlIndex": 0.45
  },
  "exposure": {
    "net": 775000.00,
    "gross": 875000.00,
    "long": 775000.00,
    "short": 0
  },
  "utilization": {
    "exposurePercent": 8.75,
    "dailyVolumePercent": 7.0,
    "openOrdersPercent": 5.0
  },
  "limits": {
    "breached": [],
    "nearBreach": [
      {
        "type": "assetExposure",
        "asset": "BTC",
        "utilizationPercent": 26.25,
        "warningThreshold": 25.0
      }
    ]
  },
  "volatility": {
    "portfolio1d": 0.025,
    "portfolio7d": 0.065,
    "varDaily95": 21875.00
  }
}

Simulate Order

Simulate how an order would impact your portfolio without actually placing it.

POST /api/sdk/risk/simulate

Required Scope: READ

Request Body

Parameter	Type	Required	Description
`side`	string	Yes	`buy` or `sell`
`asset`	string	Yes	Asset symbol
`quantity`	number	Yes	Order quantity
`price`	number	Yes	Order price

Example Request

curl -X POST https://api.zenotc.com/api/sdk/risk/simulate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature" \
  -d '{
    "side": "buy",
    "asset": "BTC",
    "quantity": 5.0,
    "price": 50000.00
  }'

simulation = api_request("POST", "/api/sdk/risk/simulate", {
    "side": "buy",
    "asset": "BTC",
    "quantity": 5.0,
    "price": 50000.00
})

Response

{
  "orderValue": 250000.00,
  "currentState": {
    "portfolioValue": 875000.00,
    "cashBalance": 100000.00,
    "exposure": 775000.00,
    "btcPosition": 10.5,
    "btcExposure": 525000.00,
    "leverage": 0.89
  },
  "afterOrder": {
    "portfolioValue": 875000.00,
    "cashBalance": -150000.00,
    "exposure": 1025000.00,
    "btcPosition": 15.5,
    "btcExposure": 775000.00,
    "leverage": 1.17
  },
  "impact": {
    "exposureChange": 250000.00,
    "exposureChangePercent": 32.26,
    "btcExposureChange": 250000.00,
    "btcExposureChangePercent": 47.62,
    "leverageChange": 0.28,
    "cashChange": -250000.00
  },
  "wouldBreach": [
    {
      "type": "availableBalance",
      "message": "Would result in negative cash balance"
    }
  ]
}

Simulation Fields

Field	Description
`currentState`	Current portfolio state before order
`afterOrder`	Projected state after order fills
`impact`	Changes caused by the order
`wouldBreach`	Limits that would be breached

Endpoints​

Get Risk Limits​

Example Request​

Response​

Limit Types​

Pre-Trade Check​

Request Body​

Example Request​

Response (Approved)​

Response (Rejected)​

Get Risk Exposure​

Example Request​

Response​

Get Asset Risk Exposure​

Path Parameters​

Example Request​

Response​

Get Limit Utilization​

Example Request​

Response​

Get Max Quantity​

Query Parameters​

Example Request​

Response​

Limiting Factors​

Get Risk Metrics​

Example Request​

Response​

Simulate Order​

Request Body​

Example Request​

Response​

Simulation Fields​

Endpoints

Get Risk Limits

Example Request

Response

Limit Types

Pre-Trade Check

Request Body

Example Request

Response (Approved)

Response (Rejected)

Get Risk Exposure

Example Request

Response

Get Asset Risk Exposure

Path Parameters

Example Request

Response

Get Limit Utilization

Example Request

Response

Get Max Quantity

Query Parameters

Example Request

Response

Limiting Factors

Get Risk Metrics

Example Request

Response

Simulate Order

Request Body

Example Request

Response

Simulation Fields