{ "openapi": "3.1.0", "info": { "title": "ChainZap Transaction Safety API", "version": "1.0.0", "description": "Tenant-scoped transaction safety checks and usage reporting. TRON is the only public network in v1." }, "servers": [ { "url": "https://api.chainzap.io" } ], "paths": { "/v1/transaction/check": { "post": { "tags": [ "Transaction Safety API" ], "summary": "Check a TRON transaction", "description": "Performs a tenant-scoped KYT check. Supplying expected_* fields adds strict recipient, token and raw-unit amount verification.", "operationId": "check_transaction_v1_transaction_check_post", "security": [ { "TransactionSafetyApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Request-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCheckRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCheckResponse" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "tenant_suspended | network_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "idempotency_conflict | idempotency_in_progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "malformed_tx_hash | invalid_network | invalid_tron_address | invalid_expected_amount | invalid_idempotency_key | payload_too_large | validation_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "rate_limit_exceeded | quota_exceeded | concurrency_limit_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "provider_unavailable | rate_limiter_unavailable | api_disabled | api_not_configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "request_timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/usage": { "get": { "tags": [ "Transaction Safety API", "Developer Account API" ], "summary": "Get tenant API usage", "description": "Returns the authenticated tenant's current UTC-month quota and a PII-minimized usage summary for up to 90 days.", "operationId": "get_usage_v1_usage_get", "security": [ { "TransactionSafetyApiKey": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 30, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "422": { "description": "validation_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "tenant_suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "rate_limit_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "rate_limiter_unavailable | api_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "request_timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "ErrorDetail": { "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "retryable": { "type": "boolean", "title": "Retryable" } }, "type": "object", "required": [ "code", "message", "retryable" ], "title": "ErrorDetail" }, "ErrorResponse": { "properties": { "request_id": { "type": "string", "title": "Request Id" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "type": "object", "required": [ "request_id", "error" ], "title": "ErrorResponse", "example": { "error": { "code": "provider_unavailable", "message": "Transaction data is temporarily unavailable", "retryable": true }, "request_id": "req-3f34a12f" } }, "ExposureResponse": { "properties": { "category": { "type": "string", "title": "Category" }, "exposure_type": { "type": "string", "title": "Exposure Type" }, "hops": { "type": "integer", "title": "Hops" }, "percent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Percent" } }, "type": "object", "required": [ "category", "exposure_type", "hops", "percent" ], "title": "ExposureResponse" }, "FreshnessResponse": { "properties": { "checked_at": { "type": "string", "format": "date-time", "title": "Checked At" }, "transaction_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Transaction At" }, "risk_data_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Risk Data At" }, "token_data_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Token Data At" }, "max_source_age_seconds": { "type": "integer", "title": "Max Source Age Seconds" } }, "type": "object", "required": [ "checked_at", "transaction_at", "risk_data_at", "token_data_at", "max_source_age_seconds" ], "title": "FreshnessResponse" }, "ReasonResponse": { "properties": { "code": { "type": "string", "title": "Code" }, "category": { "type": "string", "enum": [ "transaction", "risk", "sanctions", "token", "expected" ], "title": "Category" }, "severity": { "type": "string", "enum": [ "info", "warning", "high", "critical" ], "title": "Severity" } }, "type": "object", "required": [ "code", "category", "severity" ], "title": "ReasonResponse" }, "TransactionCheckRequest": { "properties": { "tx_hash": { "type": "string", "title": "Tx Hash" }, "network": { "type": "string", "const": "tron", "title": "Network" }, "expected_recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Recipient" }, "expected_token_contract": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Token Contract" }, "expected_amount": { "anyOf": [ { "type": "string", "maxLength": 320 }, { "type": "null" } ], "title": "Expected Amount" } }, "additionalProperties": false, "type": "object", "required": [ "tx_hash", "network" ], "title": "TransactionCheckRequest", "example": { "expected_amount": "1250.000001", "expected_recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8", "expected_token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "network": "tron", "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "TransactionCheckResponse": { "properties": { "request_id": { "type": "string", "title": "Request Id" }, "tx_hash": { "type": "string", "title": "Tx Hash" }, "network": { "type": "string", "const": "tron", "title": "Network" }, "transaction_type": { "type": "string", "title": "Transaction Type" }, "transaction_category": { "type": "string", "enum": [ "trx_transfer", "trc10_transfer", "trc20_transfer", "smart_contract_call", "smart_contract_deploy", "staking", "voting", "governance", "resource_operation", "account_operation", "exchange", "market", "permission_update", "other", "unknown" ], "title": "Transaction Category" }, "transaction_state": { "type": "string", "enum": [ "confirmed", "pending", "failed", "not_found", "unknown" ], "title": "Transaction State" }, "confirmations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Confirmations" }, "required_confirmations": { "type": "integer", "title": "Required Confirmations" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender" }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipient" }, "token_contract": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Contract" }, "token_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Symbol" }, "decimals": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Decimals" }, "amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Amount" }, "transfers": { "items": { "$ref": "#/components/schemas/TransferResponse" }, "type": "array", "title": "Transfers" }, "transfers_truncated": { "type": "boolean", "title": "Transfers Truncated" }, "aml_risk_level": { "type": "string", "enum": [ "low", "moderate", "high", "severe", "unknown" ], "title": "Aml Risk Level" }, "sanctions_hit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sanctions Hit" }, "key_exposure": { "items": { "$ref": "#/components/schemas/ExposureResponse" }, "type": "array", "title": "Key Exposure" }, "token_authenticity": { "type": "string", "enum": [ "official", "fake", "unknown" ], "title": "Token Authenticity" }, "recipient_match": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Recipient Match" }, "token_match": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Token Match" }, "amount_match": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Amount Match" }, "coverage": { "type": "string", "enum": [ "complete", "partial" ], "title": "Coverage" }, "freshness": { "$ref": "#/components/schemas/FreshnessResponse" }, "overall_state": { "type": "string", "enum": [ "CLEAR", "REVIEW", "HIGH_RISK", "LIMITED_DATA" ], "title": "Overall State" }, "reasons": { "items": { "$ref": "#/components/schemas/ReasonResponse" }, "type": "array", "maxItems": 5, "minItems": 2, "title": "Reasons" } }, "type": "object", "required": [ "request_id", "tx_hash", "network", "transaction_type", "transaction_category", "transaction_state", "confirmations", "required_confirmations", "sender", "recipient", "token_contract", "token_symbol", "decimals", "amount", "transfers", "transfers_truncated", "aml_risk_level", "sanctions_hit", "key_exposure", "token_authenticity", "recipient_match", "token_match", "amount_match", "coverage", "freshness", "overall_state", "reasons" ], "title": "TransactionCheckResponse", "example": { "aml_risk_level": "low", "amount": "1250.000001", "amount_match": true, "confirmations": 27, "coverage": "complete", "decimals": 6, "freshness": { "checked_at": "2026-09-03T12:00:00Z", "max_source_age_seconds": 4, "risk_data_at": "2026-09-03T12:00:00Z", "token_data_at": "2026-09-03T12:00:00Z", "transaction_at": "2026-09-03T11:59:00Z" }, "key_exposure": [], "network": "tron", "overall_state": "CLEAR", "reasons": [ { "category": "transaction", "code": "TX_FINALIZED", "severity": "info" }, { "category": "risk", "code": "AML_LOW", "severity": "info" } ], "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8", "recipient_match": true, "request_id": "req-3f34a12f", "required_confirmations": 19, "sanctions_hit": false, "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8", "token_authenticity": "official", "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "token_match": true, "token_symbol": "USDT", "transaction_category": "trc20_transfer", "transaction_state": "confirmed", "transaction_type": "TriggerSmartContract", "transfers": [ { "amount": "1250.000001", "asset_type": "trc20", "decimals": 6, "index": 0, "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8", "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8", "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "token_symbol": "USDT" } ], "transfers_truncated": false, "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, "TransferResponse": { "properties": { "index": { "type": "integer", "title": "Index" }, "asset_type": { "type": "string", "title": "Asset Type" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender" }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipient" }, "token_contract": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Contract" }, "token_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Id" }, "token_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Symbol" }, "decimals": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Decimals" }, "amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Amount" } }, "type": "object", "required": [ "index", "asset_type", "sender", "recipient", "token_contract", "token_id", "token_symbol", "decimals", "amount" ], "title": "TransferResponse" }, "UsageLimitsResponse": { "properties": { "rate_limit_per_minute": { "type": "integer", "title": "Rate Limit Per Minute" }, "max_concurrent_requests": { "type": "integer", "title": "Max Concurrent Requests" }, "enabled_networks": { "items": { "type": "string" }, "type": "array", "title": "Enabled Networks" } }, "type": "object", "required": [ "rate_limit_per_minute", "max_concurrent_requests", "enabled_networks" ], "title": "UsageLimitsResponse" }, "UsagePeriodResponse": { "properties": { "start": { "type": "string", "format": "date-time", "title": "Start" }, "end": { "type": "string", "format": "date-time", "title": "End" }, "used": { "type": "integer", "title": "Used" }, "reserved": { "type": "integer", "title": "Reserved" }, "limit": { "type": "integer", "title": "Limit" }, "remaining": { "type": "integer", "title": "Remaining" } }, "type": "object", "required": [ "start", "end", "used", "reserved", "limit", "remaining" ], "title": "UsagePeriodResponse" }, "UsagePlanResponse": { "properties": { "code": { "type": "string", "title": "Code" }, "version": { "type": "integer", "title": "Version" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "code", "version", "name" ], "title": "UsagePlanResponse" }, "UsageRecentResponse": { "properties": { "days": { "type": "integer", "title": "Days" }, "requests": { "type": "integer", "title": "Requests" }, "billable": { "type": "integer", "title": "Billable" }, "limited_data": { "type": "integer", "title": "Limited Data" }, "errors": { "type": "integer", "title": "Errors" }, "average_latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Average Latency Ms" }, "by_network": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Network" }, "by_overall_state": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Overall State" } }, "type": "object", "required": [ "days", "requests", "billable", "limited_data", "errors", "average_latency_ms", "by_network", "by_overall_state" ], "title": "UsageRecentResponse" }, "UsageResponse": { "properties": { "tenant_id": { "type": "string", "format": "uuid", "title": "Tenant Id" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/UsagePlanResponse" }, { "type": "null" } ] }, "limits": { "$ref": "#/components/schemas/UsageLimitsResponse" }, "period": { "$ref": "#/components/schemas/UsagePeriodResponse" }, "recent": { "$ref": "#/components/schemas/UsageRecentResponse" } }, "type": "object", "required": [ "tenant_id", "plan", "limits", "period", "recent" ], "title": "UsageResponse" } }, "securitySchemes": { "TransactionSafetyApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } } }