--- updatedAt: 2026-08-31T03:40:46.000Z agentTools: projectIndex: https://readme.cipherowl.ai/llms.txt --- # Get risk history for an address Risk-change record for one address in a pool, newest first: one record per effective-level change detected by a scan (kind=SCAN, escalations and de-escalations included), per enrollment seed (kind=ENROLL), and per baseline move (kind=REBASELINE — previous/current are baselines, not effective-level observations). Designed for compliance review — "this address was risky from D1 to D30". Records become visible a couple of minutes after they are detected (the same late-committer guard as the pool-level risk-changes feed). A freshly enrolled address may briefly return an empty page before its ENROLL seed is visible. History of soft-deleted (removed) members is included: each page carries member_deleted so the caller knows the member's current state. Shares the same record shape as the pool-level risk-changes feed. **Pagination:** Keyset pagination in reverse detection order. Default 50 items per page, max 1000 (a page_size above the max is clamped to it; a negative page_size is rejected with 400). A page_token that does not decode to a valid cursor, or that is bound to another endpoint, pool, or address, is rejected with 400. # 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/{poolId}/chains/{chain}/addresses/{address}/risk-history": { "get": { "summary": "Get risk history for an address", "description": "Risk-change record for one address in a pool, newest first: one record per effective-level change detected by a scan (kind=SCAN, escalations and de-escalations included), per enrollment seed (kind=ENROLL), and per baseline move (kind=REBASELINE — previous/current are baselines, not effective-level observations). Designed for compliance review — \"this address was risky from D1 to D30\".\n\nRecords become visible a couple of minutes after they are detected (the same late-committer guard as the pool-level risk-changes feed). A freshly enrolled address may briefly return an empty page before its ENROLL seed is visible.\n\nHistory of soft-deleted (removed) members is included: each page carries member_deleted so the caller knows the member's current state.\n\nShares the same record shape as the pool-level risk-changes feed.\n\n**Pagination:** Keyset pagination in reverse detection order. Default 50 items per page, max 1000 (a page_size above the max is clamped to it; a negative page_size is rejected with 400). A page_token that does not decode to a valid cursor, or that is bound to another endpoint, pool, or address, is rejected with 400.", "operationId": "MonitoringService_GetAddressRiskHistory", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1GetAddressRiskHistoryResponse" } } } } }, "parameters": [ { "name": "poolId", "description": "Pool id, as returned by CreatePool/ListPools (a UUID). At most 64 bytes.", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chain", "description": "Chain of the address (for example evm). At most 128 bytes.", "in": "path", "required": true, "schema": { "type": "string", "example": "bitcoin" } }, { "name": "address", "description": "Address — normalized the same way AddAddresses normalizes it. At most\n1024 bytes.", "in": "path", "required": true, "schema": { "type": "string", "example": "17mhyeBX617ABZ1ffThhUTJkHUcMvCkfd5" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "description": "Opaque token from a previous GetAddressRiskHistory response for this\npool and address — tokens are bound to the endpoint, pool, and address\nthat issued them. At most 1024 bytes.", "in": "query", "required": false, "schema": { "type": "string" } } ], "tags": [ "Continuous Monitoring" ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth 2.0 access token obtained from /oauth/token using client credentials." } }, "schemas": { "v1GetAddressRiskHistoryResponse": { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/v1RiskChangeRecord" }, "description": "The full flip record, newest first. Shares the RiskChangeRecord shape\nwith the pool-level risk-changes feed." }, "nextPageToken": { "type": "string" }, "memberDeleted": { "type": "boolean", "description": "Whether the member is currently soft-deleted (removed from the pool).\nHistory is still served — this endpoint is an audit view. Explicit\npresence so `member_deleted: false` is emitted on the wire (proto3\nbool + EmitUnpopulated=false would omit it for live members)." } } }, "v1RiskAssessment": { "type": "object", "properties": { "riskFound": { "type": "boolean", "description": "Convenience bool derived from risk_level: true iff risk_level != LOW." }, "riskConfig": { "type": "string", "description": "The attributed risk config - normally the highest-level config that\nfound risk; on a scan record of a risky-to-LOW change, the previously\nrisky config. Empty for baselines (they record a level, not a config)\nand for members whose latest level is LOW." }, "riskLevel": { "allOf": [ { "$ref": "#/components/schemas/v1RiskLevel" } ], "description": "The effective risk level: the highest level among the pool's configs\nthat found risk; LOW means no risk found." } } }, "v1RiskChangeKind": { "type": "string", "enum": [ "RISK_CHANGE_KIND_UNSPECIFIED", "SCAN", "ENROLL", "REBASELINE" ], "default": "RISK_CHANGE_KIND_UNSPECIFIED", "description": "What kind of event a risk change record describes.\n\n - SCAN: An effective-level change detected by a periodic scan.\n - ENROLL: The enrollment seed: the level accepted as baseline when the address\nwas added.\n - REBASELINE: An operator baseline move (previous/current are baselines, not scan\nresults)." }, "v1RiskChangeRecord": { "type": "object", "properties": { "poolId": { "type": "string" }, "chain": { "type": "string", "description": "Canonical chain (e.g. evm)." }, "address": { "type": "string", "description": "Normalized address." }, "initialRisk": { "allOf": [ { "$ref": "#/components/schemas/v1RiskAssessment" } ], "description": "The member's baseline (initial_risk_level) as it stands NOW, not as of\nthis record: it is a mutable member column that a re-baseline moves, so\nre-reading an older page after a re-baseline returns the new value.\nLevel only - baselines carry no attributed config. Carried here so a\nconsumer can answer \"how far has this address drifted from what we\nsigned off on\" without a second call." }, "currentRisk": { "allOf": [ { "$ref": "#/components/schemas/v1RiskAssessment" } ], "description": "Effective level after the change, with its attributed config." }, "detectedAt": { "type": "string", "format": "date-time", "description": "When the change was detected." }, "previousRisk": { "allOf": [ { "$ref": "#/components/schemas/v1RiskAssessment" } ], "description": "Effective level before the change (equals current_risk for ENROLL\nseeds). Level only - the record's attributed config is on current_risk." }, "kind": { "$ref": "#/components/schemas/v1RiskChangeKind" }, "changeId": { "type": "string", "description": "Stable record id; treat as an idempotency key when polling." } } }, "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." } } } } ```