{ "openapi": "3.1.0", "info": { "title": "Tennto Risk API", "version": "1.0.0", "description": "Solana wallet and proposed-transfer risk intelligence. Fast mode returns the completed assessment inline; default-mode research is asynchronous and produces a cited report with a final Jev score when evidence is sufficient. Tennto does not sign transactions or return a binding approval verdict. Customers enforce their own policy. Examples are illustrative, not findings about an address." }, "servers": [ { "url": "https://trustauthy-api.reiun-ni.workers.dev" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/risk": { "post": { "operationId": "startRiskAssessment", "summary": "Start a Solana risk assessment", "description": "Fast mode returns HTTP 200 with status completed and result. Default mode returns HTTP 202 with status queued; poll the run URL with an API key belonging to the same user. Both return a retrievable runId. Limit: 20 starts per 24 hours per user across keys; 300 authenticated requests per minute, including polls. Quota windows start on first use. POST is not idempotent; do not automatically retry an uncertain submission.", "x-body-limit-bytes": 16384, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskRequest" }, "example": { "address": "5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1", "chain": "solana", "mode": "fast" } } } }, "responses": { "200": { "description": "Fast assessment completed inline; includes the saved result and runId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskCompleted" } } } }, "202": { "description": "Default research accepted; poll using runId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskQueued" }, "example": { "runId": "example-run", "status": "queued" } } } }, "400": { "description": "Invalid input (validation_error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key (unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Request exceeds the body-size limit (http_error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Per-user quota exceeded (rate_limited). Polling also consumes the request quota. No Retry-After header is guaranteed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error (internal_error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Unable to launch or complete assessment, or invalid upstream result (risk_start_failed, risk_execution_failed, invalid_risk_result).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Credential/quota service, fast-run configuration, or result storage unavailable (api_keys_unavailable, risk_configuration_unavailable, risk_storage_unavailable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/risk/{runId}": { "get": { "operationId": "getRiskAssessment", "summary": "Read an assessment owned by the API key user", "description": "Result can be null or partial while running. Terminal statuses are completed, failed and canceled. The shared response schema also permits credits_exhausted; handle it as terminal. Always inspect assessment status, sanctions, limitations and reportStatus; completion is not a safety verdict. Responses are not cached.", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Owner-checked run status and available result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskRun" } } } }, "400": { "description": "Invalid input (validation_error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, revoked or expired API key (unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Run unavailable or not owned by this user (not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Per-user quota exceeded (rate_limited). Polling also consumes the request quota. No Retry-After header is guaranteed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected server error (internal_error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Invalid upstream assessment result (invalid_risk_result).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Credential/quota service, fast-run configuration, or result storage unavailable (api_keys_unavailable, risk_configuration_unavailable, risk_storage_unavailable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Named, expiring, revocable Tennto API key. Keep it server-side; this is not a Clerk session token." } }, "schemas": { "RiskRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "Base58-encoded 32-byte Solana public key. The server also validates decoded byte length." }, "chain": { "type": "string", "const": "solana" }, "mode": { "default": "default", "type": "string", "enum": [ "default", "fast" ] }, "query": { "default": "Assess the risk indicated by the available evidence.", "type": "string", "maxLength": 2000 }, "transaction": { "type": "object", "properties": { "receiver": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "Base58-encoded 32-byte Solana public key. The server also validates decoded byte length." }, "value": { "type": "number", "exclusiveMinimum": 0 }, "tokenSymbol": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "receiver", "value", "tokenSymbol" ], "additionalProperties": false } }, "required": [ "address", "chain" ], "additionalProperties": false }, "RiskQueued": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string" }, "status": { "type": "string", "const": "queued" } }, "required": [ "runId", "status" ], "additionalProperties": false }, "RiskCompleted": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string" }, "status": { "type": "string", "const": "completed" }, "result": { "type": "object", "properties": { "activity": { "maxItems": 128, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9:_-]{1,100}$" }, "parentId": { "type": "string", "pattern": "^[A-Za-z0-9:_-]{1,100}$" }, "kind": { "type": "string", "enum": [ "agent", "tool", "stage" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] }, "at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "detail": { "type": "string", "maxLength": 300 } }, "required": [ "id", "kind", "name", "status", "at" ], "additionalProperties": false } }, "mode": { "type": "string", "enum": [ "default", "fast" ] }, "assessment": { "type": "object", "properties": { "score": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "assessed", "review_required", "insufficient_evidence", "unavailable", "report_only" ] }, "source": { "type": "string", "enum": [ "jev", "sanctions_policy", "none" ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "probabilities": { "anyOf": [ { "type": "object", "properties": { "0": { "type": "number", "minimum": 0, "maximum": 1 }, "1": { "type": "number", "minimum": 0, "maximum": 1 }, "2": { "type": "number", "minimum": 0, "maximum": 1 }, "3": { "type": "number", "minimum": 0, "maximum": 1 }, "4": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "0", "1", "2", "3", "4" ], "additionalProperties": false }, { "type": "null" } ] }, "policyVersion": { "type": "string" }, "sanctions": { "type": "string", "enum": [ "clear", "matched", "unknown" ] }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "score", "status", "source", "model", "confidence", "probabilities", "policyVersion", "sanctions", "limitations" ], "additionalProperties": false }, "evidence": { "type": "object", "properties": { "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "Base58-encoded 32-byte Solana public key. The server also validates decoded byte length." }, "receiver": { "anyOf": [ { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "Base58-encoded 32-byte Solana public key. The server also validates decoded byte length." }, { "type": "null" } ] }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "sampledTransactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "historyHasMore": { "type": "boolean" }, "historyAvailable": { "type": "boolean" }, "labelsAvailable": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "label", "category" ], "additionalProperties": false } }, "counterpartyLabels": { "type": "array", "items": { "type": "string" } }, "outgoingTransferCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sanctions": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "Base58-encoded 32-byte Solana public key. The server also validates decoded byte length." }, "status": { "type": "string", "enum": [ "clear", "matched", "unknown" ] } }, "required": [ "address", "status" ], "additionalProperties": false } }, "anomaly": { "anyOf": [ { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "ratioToMean": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baseline": { "anyOf": [ { "type": "object", "properties": { "sampleSize": { "type": "number" }, "mean": { "type": "number" }, "max": { "type": "number" } }, "required": [ "sampleSize", "mean", "max" ], "additionalProperties": false }, { "type": "null" } ] }, "inconclusive": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "severity", "ratioToMean", "baseline", "inconclusive", "reasons" ], "additionalProperties": false }, { "type": "null" } ] }, "limitations": { "type": "array", "items": { "type": "string" } }, "creditsUsed": { "type": "number", "minimum": 0 }, "creditsEstimated": { "type": "boolean" }, "holdings": { "anyOf": [ { "type": "object", "properties": { "tokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalValueUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "topHoldings": { "type": "array", "items": { "type": "object", "properties": { "tokenSymbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "valueUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "tokenSymbol", "valueUsd" ], "additionalProperties": false } } }, "required": [ "tokenCount", "totalValueUsd", "topHoldings" ], "additionalProperties": false }, { "type": "null" } ] }, "relatedWallets": { "anyOf": [ { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "labels": { "type": "array", "items": { "type": "string" } }, "relations": { "type": "array", "items": { "type": "string" } } }, "required": [ "count", "labels", "relations" ], "additionalProperties": false }, { "type": "null" } ] }, "counterpartySummary": { "anyOf": [ { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "top": { "type": "array", "items": { "type": "object", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "interactionCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalVolumeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "label", "interactionCount", "totalVolumeUsd" ], "additionalProperties": false } } }, "required": [ "count", "top" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "address", "receiver", "dateFrom", "dateTo", "sampledTransactions", "historyHasMore", "historyAvailable", "labelsAvailable", "labels", "counterpartyLabels", "outgoingTransferCount", "sanctions", "anomaly", "limitations", "creditsUsed" ], "additionalProperties": false }, "report": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reportStatus": { "type": "string", "enum": [ "pending", "skipped", "completed", "failed" ] }, "timings": { "type": "object", "properties": { "evidenceMs": { "type": "number", "minimum": 0 }, "scoringMs": { "type": "number", "minimum": 0 }, "reportMs": { "type": "number", "minimum": 0 } }, "required": [ "evidenceMs", "scoringMs", "reportMs" ], "additionalProperties": false } }, "required": [ "mode", "assessment", "evidence", "report", "reportStatus", "timings" ], "additionalProperties": false } }, "required": [ "runId", "status", "result" ], "additionalProperties": false }, "RiskRun": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "activity": { "maxItems": 128, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9:_-]{1,100}$" }, "parentId": { "type": "string", "pattern": "^[A-Za-z0-9:_-]{1,100}$" }, "kind": { "type": "string", "enum": [ "agent", "tool", "stage" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] }, "at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "detail": { "type": "string", "maxLength": 300 } }, "required": [ "id", "kind", "name", "status", "at" ], "additionalProperties": false } }, "runId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "credits_exhausted", "canceled" ] }, "result": { "anyOf": [ { "type": "object", "properties": { "activity": { "maxItems": 128, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9:_-]{1,100}$" }, "parentId": { "type": "string", "pattern": "^[A-Za-z0-9:_-]{1,100}$" }, "kind": { "type": "string", "enum": [ "agent", "tool", "stage" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "canceled" ] }, "at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "detail": { "type": "string", "maxLength": 300 } }, "required": [ "id", "kind", "name", "status", "at" ], "additionalProperties": false } }, "mode": { "type": "string", "enum": [ "default", "fast" ] }, "assessment": { "type": "object", "properties": { "score": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "assessed", "review_required", "insufficient_evidence", "unavailable", "report_only" ] }, "source": { "type": "string", "enum": [ "jev", "sanctions_policy", "none" ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "probabilities": { "anyOf": [ { "type": "object", "properties": { "0": { "type": "number", "minimum": 0, "maximum": 1 }, "1": { "type": "number", "minimum": 0, "maximum": 1 }, "2": { "type": "number", "minimum": 0, "maximum": 1 }, "3": { "type": "number", "minimum": 0, "maximum": 1 }, "4": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "0", "1", "2", "3", "4" ], "additionalProperties": false }, { "type": "null" } ] }, "policyVersion": { "type": "string" }, "sanctions": { "type": "string", "enum": [ "clear", "matched", "unknown" ] }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "score", "status", "source", "model", "confidence", "probabilities", "policyVersion", "sanctions", "limitations" ], "additionalProperties": false }, "evidence": { "type": "object", "properties": { "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "Base58-encoded 32-byte Solana public key. The server also validates decoded byte length." }, "receiver": { "anyOf": [ { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "Base58-encoded 32-byte Solana public key. The server also validates decoded byte length." }, { "type": "null" } ] }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "sampledTransactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "historyHasMore": { "type": "boolean" }, "historyAvailable": { "type": "boolean" }, "labelsAvailable": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "label", "category" ], "additionalProperties": false } }, "counterpartyLabels": { "type": "array", "items": { "type": "string" } }, "outgoingTransferCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sanctions": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "Base58-encoded 32-byte Solana public key. The server also validates decoded byte length." }, "status": { "type": "string", "enum": [ "clear", "matched", "unknown" ] } }, "required": [ "address", "status" ], "additionalProperties": false } }, "anomaly": { "anyOf": [ { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "ratioToMean": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baseline": { "anyOf": [ { "type": "object", "properties": { "sampleSize": { "type": "number" }, "mean": { "type": "number" }, "max": { "type": "number" } }, "required": [ "sampleSize", "mean", "max" ], "additionalProperties": false }, { "type": "null" } ] }, "inconclusive": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "severity", "ratioToMean", "baseline", "inconclusive", "reasons" ], "additionalProperties": false }, { "type": "null" } ] }, "limitations": { "type": "array", "items": { "type": "string" } }, "creditsUsed": { "type": "number", "minimum": 0 }, "creditsEstimated": { "type": "boolean" }, "holdings": { "anyOf": [ { "type": "object", "properties": { "tokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalValueUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "topHoldings": { "type": "array", "items": { "type": "object", "properties": { "tokenSymbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "valueUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "tokenSymbol", "valueUsd" ], "additionalProperties": false } } }, "required": [ "tokenCount", "totalValueUsd", "topHoldings" ], "additionalProperties": false }, { "type": "null" } ] }, "relatedWallets": { "anyOf": [ { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "labels": { "type": "array", "items": { "type": "string" } }, "relations": { "type": "array", "items": { "type": "string" } } }, "required": [ "count", "labels", "relations" ], "additionalProperties": false }, { "type": "null" } ] }, "counterpartySummary": { "anyOf": [ { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "top": { "type": "array", "items": { "type": "object", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "interactionCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalVolumeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "label", "interactionCount", "totalVolumeUsd" ], "additionalProperties": false } } }, "required": [ "count", "top" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "address", "receiver", "dateFrom", "dateTo", "sampledTransactions", "historyHasMore", "historyAvailable", "labelsAvailable", "labels", "counterpartyLabels", "outgoingTransferCount", "sanctions", "anomaly", "limitations", "creditsUsed" ], "additionalProperties": false }, "report": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reportStatus": { "type": "string", "enum": [ "pending", "skipped", "completed", "failed" ] }, "timings": { "type": "object", "properties": { "evidenceMs": { "type": "number", "minimum": 0 }, "scoringMs": { "type": "number", "minimum": 0 }, "reportMs": { "type": "number", "minimum": 0 } }, "required": [ "evidenceMs", "scoringMs", "reportMs" ], "additionalProperties": false } }, "required": [ "mode", "assessment", "evidence", "report", "reportStatus", "timings" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "runId", "status", "result" ], "additionalProperties": false }, "ApiError": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }