---
updatedAt: 2026-08-14T01:21:22.000Z
agentTools:
  projectIndex: https://readme.cipherowl.ai/llms.txt
---

# Create a new address pool

Creates a new address pool for monitoring addresses.

**Business Rules:**
- Pool name must be unique within your organization.
- risk_configs is required (1..3 entries): each entry binds one risk config to one risk level. Levels must be unique within the pool, a config may be bound only once, and LOW cannot be bound (it is the no-risk floor).
- open_case_risk_levels is optional; every entry must be one of the levels mapped in risk_configs. A clean-to-risky flip at one of these levels opens a case.
- Config-to-level bindings are immutable after creation. Name and open_case_risk_levels can be changed via UpdatePool.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "API ENDPOINTS",
    "description": "CipherOwl blockchain compliance and risk assessment APIs.",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://svc.cipherowl.ai"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Continuous Monitoring",
      "description": "Monitor pools of blockchain addresses for risk changes. Create address pools, manage their membership, re-baseline accepted risk, and consume the pool's time-ordered feed of risk-change events (or one address's history). Members are identified by chain (e.g. `evm`) and address."
    }
  ],
  "paths": {
    "/api/monitoring/v1/pools": {
      "post": {
        "summary": "Create a new address pool",
        "description": "Creates a new address pool for monitoring addresses.\n\n**Business Rules:**\n- Pool name must be unique within your organization.\n- risk_configs is required (1..3 entries): each entry binds one risk config to one risk level. Levels must be unique within the pool, a config may be bound only once, and LOW cannot be bound (it is the no-risk floor).\n- open_case_risk_levels is optional; every entry must be one of the levels mapped in risk_configs. A clean-to-risky flip at one of these levels opens a case.\n- Config-to-level bindings are immutable after creation. Name and open_case_risk_levels can be changed via UpdatePool.",
        "operationId": "MonitoringService_CreatePool",
        "responses": {
          "200": {
            "description": "A successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/v1CreatePoolResponse"
                }
              }
            }
          }
        },
        "parameters": [],
        "tags": [
          "Continuous Monitoring"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/v1CreatePoolRequest"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "OAuth 2.0 access token obtained from /oauth/token using client credentials."
      }
    },
    "schemas": {
      "v1AddressPool": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "organization": {
            "type": "string"
          },
          "createdBy": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "riskConfigs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/v1RiskConfigBinding"
            },
            "description": "Config-to-level bindings, highest level first."
          },
          "openCaseRiskLevels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/v1RiskLevel"
            },
            "description": "Mapped levels at which a clean-to-risky flip opens a case."
          }
        }
      },
      "v1CreatePoolRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Required; must contain non-whitespace characters and be unique within\nthe organization. At most 256 bytes."
          },
          "description": {
            "type": "string",
            "description": "Optional. At most 4096 bytes."
          },
          "riskConfigs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/v1RiskConfigBinding"
            },
            "description": "Required, 1..3 entries: levels unique within the pool, a config may be\nbound only once, LOW and RISK_LEVEL_UNSPECIFIED are rejected."
          },
          "openCaseRiskLevels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/v1RiskLevel"
            },
            "description": "Optional; every entry must be one of the levels mapped in risk_configs.\nAt most 16 entries."
          }
        }
      },
      "v1CreatePoolResponse": {
        "type": "object",
        "properties": {
          "pool": {
            "$ref": "#/components/schemas/v1AddressPool"
          }
        }
      },
      "v1RiskConfigBinding": {
        "type": "object",
        "properties": {
          "riskConfig": {
            "type": "string",
            "description": "Risk config name. At most 256 bytes."
          },
          "riskLevel": {
            "$ref": "#/components/schemas/v1RiskLevel"
          }
        },
        "description": "One risk config bound to one risk level on a pool."
      },
      "v1RiskLevel": {
        "type": "string",
        "enum": [
          "RISK_LEVEL_UNSPECIFIED",
          "SEVERE",
          "HIGH",
          "MEDIUM",
          "LOW"
        ],
        "default": "RISK_LEVEL_UNSPECIFIED",
        "description": "Ordered risk levels: SEVERE > HIGH > MEDIUM > LOW. LOW is the \"no risk\nfound\" floor — it can never be bound to a risk config and never appears in\nopen_case_risk_levels."
      }
    }
  }
}
```