Alerts

Suspicious transaction activity alerts requiring investigation.

Field	Key	Data Type	Required	Max Length	Description
Alert ID	`alert_id`	string	Yes	36	Unique identifier for each alert in your system
Entity ID List	`entity_id_list`	array[string]	Yes	-	List of associated Entity IDs that must map to previously submitted entities
Flagged Transaction ID List	`flagged_transaction_id_list`	array[string]	Yes	-	Array of Transaction IDs flagged by this alert (must map to submitted transactions)
Alert Source	`source`	string enum value	Yes	-	`TM` (Transaction Monitoring) or `BM` (Blockchain Monitoring)
Alert Title	`title`	string	Yes	-	Alert title displayed in Rose UI for reference
Alert Description	`description`	string	No	-	Free-form description for Rose analysis
Status	`status`	string enum value	Yes	-	`OPEN` or `CLOSED` (Rose only analyzes OPEN alerts)
Created At	`created_at`	string	Yes	-	ISO8601 datetime when alert was created
Rule Title	`rule_title`	string	Yes	-	Title of the rule that triggered the alert
Disposition Status	`disposition_status`	string enum value	No	-	`UNDER_INVESTIGATION`, `PENDING_INFO`, `ESCALATED`, `MONITORING`, `SUSPICIOUS_CONFIRMED`, `STR_FILED`, `CLOSED`, `CLEARED`, `NON_REFERRAL`, `REOPENED`
Disposition Notes	`disposition_notes`	string	No	-	Free text for disposition narratives and notes
Dispositioned At	`dispositioned_at`	string	No	-	ISO8601 datetime when disposition was set
Dispositioned By	`dispositioned_by`	string	No	-	Email address of team member who changed disposition
Start Date	`start_date`	string	No	-	ISO8601 datetime of first flagged transaction
End Date	`end_date`	string	No	-	ISO8601 datetime of last flagged transaction
Reference IDs'	`reference_ids`	array[string]	No	-	Send multiple reference ids for that alert for mapping
Alert Sub Type	`alert_subtype`	string	No	-	Alert subtype classification (e.g., DIRECT, INDIRECT)
Crypto Transferred Value Percentage	`crypto_transferred_value_percentage`	float	No	-	Percentage of crypto transferred value associated with the alert (0-100)

Entities API Data Model

Entities (Main Model)

Individual persons and business entities involved in transactions.

Field	Key	Data Type	Required	Max Length	Description
Entity ID	`entity_id`	string	Yes	36	Unique identifier for each entity in your system
Type	`type`	string enum value	Yes	-	`INDIVIDUAL` or `BUSINESS`
Date of Birth	`dob`	string	No	-	ISO8601 date format `YYYY-MM-DD`
Corporate Tax ID	`corporate_tax_id`	string	No	-	Corporate identifier (EIN, FEIN, BN, UTR, CRN, etc.)
Corporate Tax ID Type	`corporate_tax_id_type`	string	No	-	Type of tax ID (EIN, FEIN, BN, UTR, CRN, Steuernummer, etc.)
Emails	`emails`	array[string]	No	-	List of email addresses
Gender	`gender`	string enum value	No	-	`MALE` or `FEMALE`
Occupation	`occupation`	string	No	-	Individual's occupation
Name	`name`	string	No	-	Legal name of entity
Account Holder Name	`account_holder_name`	string	No	-	Name of person associated with business account
IP Addresses	`ip_addresses`	array[string]	No	-	IPv4 or IPv6 addresses
Phone Numbers	`phone_numbers`	array[string]	No	-	Phone numbers in E.164 format
Registered At	`registered_at`	string	No	-	ISO8601 datetime when entity registered
Mailing Street Address	`mailing_street_address`	string	No	-	Street address
Mailing City	`mailing_city`	string	No	-	City/locality
Mailing State	`mailing_state`	string	No	-	State/province/region
Mailing Postal Code	`mailing_postal_code`	string	No	-	Postal/zip code
Mailing Country	`mailing_country`	string	No	-	ISO 3166 alpha-2 country code
Website	`website`	string	No	-	Business website URL
Verification Tier	`verification_tier`	string	No	64	KYC/verification tier level
Purpose of Account	`purpose_of_account`	array[string]	No	-	Purpose or intended use of the account
Industry	`industry`	string	No	-	Business industry classification
Source of Funds	`source_of_funds`	array[string]	No	-	Origin of account holder's funds
Source of Wealth	`source_of_wealth`	array[string]	No	-	Origin of account holder's overall wealth
Employment Status	`employment_status`	string	No	-	Employment status (e.g. "employed", "self_employed", "retired")
Nationality	`nationality`	array[string]	No	-	ISO 3166 Alpha-2 country codes. Multiple nationalities supported
Citizenship	`citizenship`	array[string]	No	-	ISO 3166 Alpha-2 country codes. Multiple citizenships supported
Tags	`tags`	array[string]	No	-	Free-text labels/tags/flags
Estimated Monthly Deposits	`estimated_monthly_deposits`	MonetaryRange	No	-	Expected monthly deposit volume range (see MonetaryRange)
Estimated Monthly Withdrawals	`estimated_monthly_withdrawals`	MonetaryRange	No	-	Expected monthly withdrawal volume range (see MonetaryRange)
Estimated Trades Per Month	`estimated_trades_per_month`	BaseRange	No	-	Expected trades per month (see BaseRange)
Net Worth	`net_worth`	MonetaryRange	No	-	Declared net worth range (see MonetaryRange)
Annual Income	`annual_income`	MonetaryRange	No	-	Declared annual income range (see MonetaryRange)
UBO	`ubo`	UBOData	No	-	Ultimate Beneficial Owner data (see UBOData)
Blockchain Intel	`blockchain_intel`	array[BlockchainIntel]	No	-	Customer-supplied KYT Data (see BlockchainIntel)

MonetaryRange

Used for monetary estimates (deposits, withdrawals, income, net worth).

Field	Key	Data Type	Required	Description
Lower Bound	`lower_bound`	integer	No*	Lower bound of the range
Upper Bound	`upper_bound`	integer	No*	Upper bound of the range
Currency	`currency`	integer	Yes	Currency ID from Axle's supported currencies

*At least one of lower_bound or upper_bound must be provided.

BaseRange

Used for count-based estimates (e.g. trades per month)

Field	Key	Data Type	Required	Max Length	Description
Lower Bound	`lower_bound`	integer	No*		Lower bound of the range
Upper Bound	`upper_bound`	integer	No*		Upper bound of the range

*At least one of lower_bound or upper_bound must be provided.

UBOData

Field	Key	Data Type	Required	Max Length	Description
Individual UBOs	`individual`	array[IndividualUBO]	No*		Array of individual person UBOs
Corporate UBOs	`corporate`	array[CorporateUBO]	No*		Array of corporate entity UBOs

*At least one of individual or corporate must contain entries.

IndividualUBO

Field	Key	Data Type	Required	Max Length	Description
ID	`id`	integer	Yes		Client-provided unique ID within this payload
First Name	`first_name`	string	Yes	256	First/given name
Middle Name	`middle_name`	string	No	256	Middle name
Last Name	`last_name`	string	Yes		Last name
DOB	`dob`	string	No	10	ISO8601 date format `YYYY-MM-DD`
Email	`email`	string	No		Email address
Phone	`phone`	string	No		Phone number in E.164 format
Nationality	`nationality`	array[string]	No		ISO 3166 Alpha-2 country codes
Citizenship	`citizenship`	array[string]	No		ISO 3166 Alpha-2 country codes
Country of Birth	`country_of_birth`	string	No		ISO 3166 Alpha-2 country code
City of Birth	`city_of_birth`	string	No		City of birth
Tax Residency	`tax_residency`	array[string]	No		ISO 3166 Alpha-2 country codes
Ownership Percentage	`ownership_percentage`	float	No		Ownership stake (0-100)
Role	`role`	string	No		Job title / role
Controller	`controller`	bool	No		Has control of corporation (CEO, CFO, owner or equivalent)
Street Address	`street_address`	string	No		Street address
City	`city`	string	No	256	City
State	`state`	string	No	256	State or province
Postal Code	`postal_code`	string	No	32	Postal/ZIP code
Country	`country`	string	No		ISO 3166 Alpha-2 country code

CorporateUBO

Field	Key	Data Type	Required	Max Length	Description
ID	`id`	integer	Yes		Client-provided unique ID within this payload
Entity Name	`entity_name`	string	Yes	256	Legal entity name
Formation Country	`formation_country`	string	No		ISO 3166 Alpha-2 code
Formation Date	`formation_date`	string	No	10	Date of formation (YYYY-MM-DD)
Ownership Percentage	`ownership_percentage`	float	No		Ownership stake (0-100)
Street Address	`street_address`	string	No		Street address
City	`city`	string	No	256	City
State	`state`	string	No	256	State or province
Postal Code	`postal_code`	string	No	32	Postal/ZIP code
Country	`country`	string	No		ISO 3166 Alpha-2 country code
Children	`children`	array[UBOChild]	No		Child UBOs relationship

UBOChild

Field	Key	Data Type	Required	Max Length	Description
ID	`id`	integer	Yes		References another UBO's id in the same payload
Relative Ownership	`relative_ownership`	float	No		Ownership percentage the child has of this corporate UBO (0-100)

Transaction API Data Model

Transaction (Main Model)

Field	Key	Data Type	Required	Max Length	Description
Transaction ID	`transaction_id`	string	Yes	255	Unique identifier in your system
Type	`type`	Transaction Types(ENUM)	No	-	Transaction type (see Transaction Types below)
Subtype	`subtype`	Transaction Subtypes(ENUM)	No	-	Transaction subtype (see Transaction Subtypes below)
Event Time	`event_time`	string	Yes	-	ISO8601 datetime (YYYY-MM-DDTHH:MM:SS or YYYY-MM-DDTHH:MM:SSZ)
Amount	`amount`	string	Yes	-	Transaction value as decimal string (e.g., "1234.56")
Amount Currency	`amount_currency`	string enum value	Yes	-	Currency enum for `amount` (e.g., "USD" - see currency endpoints)
Sender	`sender`	TransactionSender	No	-	Transaction sender details (see TransactionSender model)
Receiver	`receiver`	TransactionReceiver	No	-	Transaction receiver details (see TransactionReceiver model)
Balance	`balance`	string	No	-	Account balance after transaction as decimal string
Blockchain	`blockchain`	BlockchainDetails	No	-	Blockchain transaction details (see BlockchainDetails model)
Status	`status`	TransactionStatus	No	-	Current Status of the Transaction
Descriptor	`descriptor`	string	No	-	Additional description of the transaction
Tags	`tags`	array[string]	No	-	Free-form tags associated with the transaction

TransactionSender

Field	Key	Data Type	Required	Max Length	Description
Entity ID	`entity_id`	string	No*	-	Unique entity identifier (must map to submitted entity)
Name	`name`	string	No*	-	Entity name (mutually exclusive with entity_id)
Blockchain Addresses	`blockchain_addresses`	array[string]	No	-	Associated blockchain addresses
Asset Out	`asset_out`	CurrencyAmount	No	-	Asset going out from sender (see CurrencyAmount model)
Blockchain Intel	`blockchain_intel`	array[BlockchainIntel]	No	-	Customer-supplied KYT Data (see BlockchainIntel)

*Either entity_id or name can be provided, but not both

TransactionReceiver

Field	Key	Data Type	Required	Max Length	Description
Entity ID	`entity_id`	string	No*	-	Unique entity identifier (must map to submitted entity)
Name	`name`	string	No*	-	Entity name (mutually exclusive with entity_id)
Blockchain Addresses	`blockchain_addresses`	array[string]	No	-	Associated blockchain addresses
Asset In	`asset_in`	CurrencyAmount	No	-	Asset coming in to receiver (see CurrencyAmount model)
Blockchain Intel	`blockchain_intel`	array[BlockchainIntel]	No	-	Customer-supplied KYT Data

*Either entity_id or name can be provided, but not both

CurrencyAmount

Field	Key	Data Type	Required	Max Length	Description
Amount	`amount`	string	Yes	-	Amount value as decimal string (e.g., "123.456")
Currency ID	`currency_id`	integer	No*	-	Currency identifier
Currency Type	`currency_type`	string enum value	No*	-	Type of currency: `FIAT` or `CRYPTO`

*Both currency_id and currency_type must be provided together or both omitted

BlockchainDetails

Field	Key	Data Type	Required	Max Length	Description
Transaction Hash	`transaction_hash`	string	No	-	Transaction hash on the blockchain
Chain ID	`chain_id`	integer	No	-	Blockchain network identifier (see chain endpoints)

Transaction Types

String Enum Value	Description
`DEPOSIT`	All funding operations
`WITHDRAWAL`	All cash-out operations
`PAYMENT`	All payment operations
`TRANSFER`	All transfer operations
`TRADE`	All trading operations
`FEE`	All fee operations
`CREDIT`	All credit operations
`INTEREST`	All interest/reward operations
`LOAN`	All loan operations
`REMITTANCE`	All remittance operations
`INTERNAL`	All internal operations
`CHARGEBACK`	All chargeback operations
`OTHER`	All other/unspecified operations
`TRANSACTION`	Generic transaction type

Transaction Subtypes

String Enum Value	Description
`TRADE`	All trading operations
`MARGIN`	Margin trading operations
`PTL-SALE`	Private token launch sales
`EARN_ALLOCATION`	Earning program allocations
`EARN_REWARD`	Earning program rewards
`STAKING`	All staking operations
`REWARD`	Generic rewards and dividends
`ROLLOVER`	Investment rollovers
`DEPOSIT_BANK`	Traditional bank deposits
`DEPOSIT_CRYPTO`	All cryptocurrency deposits
`DEPOSIT_FIAT`	Fiat currency deposits
`DEPOSIT_PROCESSOR`	Payment processor deposits
`ACCOUNT_DEPOSIT`	Account funding operations
`VAULT_DEPOSIT`	Vault/savings deposits
`WITHDRAWAL_BANK`	Traditional bank withdrawals
`WITHDRAWAL_CRYPTO`	All cryptocurrency withdrawals
`WITHDRAWAL_FIAT`	Fiat currency withdrawals
`WITHDRAWAL_PROCESSOR`	Payment processor withdrawals
`CASH_WITHDRAWAL`	ATM/cash withdrawals
`VAULT_WITHDRAWAL`	Vault/savings withdrawals
`E_TRANSFER_SENT`	Electronic transfer sent
`E_TRANSFER_RECEIVED`	Electronic transfer received
`INTERNAL_TRANSFER`	Internal account transfers
`BALANCE_TRANSFER`	Balance transfers between accounts
`P2P_TRANSFER`	Person-to-person transfers
`WIRE_TRANSFER`	Wire transfers
`ACH_TRANSFER`	ACH batch-based transfers
`RTP_TRANSFER`	Real-Time Payments transfers
`CHECK_TRANSFER`	Physical check transfers
`CARD_PURCHASE`	Card-based purchases
`BILL_PAYMENT`	Bill payment transactions
`LOAN_REPAYMENT`	Loan repayment transactions
`CRYPTO_PAYMENT`	Cryptocurrency payment transactions
`CARD_SETTLEMENT`	Card settlement operations
`SERVICE_FEE`	Service fees
`SUBSCRIPTION_FEE`	Subscription fees
`CASHBACK`	Cashback rewards
`CREDIT_TRANSACTION`	Credit transactions
`PROMOTIONAL_CREDIT`	Promotional credits
`INTEREST_EARNED`	Interest earned
`INTEREST_CHARGED`	Interest charged
`TRAVEL_EXPENSE`	Travel-related expenses
`SETTLED`	Settlement operations
`PREPAID_CARD_LOAD`	Prepaid Card Load

Transaction Status

Status
`PENDING`
`PROCESSING`
`AUTHORIZED`
`COMPLETED`
`FAILED`
`DECLINED`
`CANCELLED`
`REFUNDED`
`PARTIALLY_REFUNDED`
`REVERSED`
`ON_HOLD`
`EXPIRED`
`SCHEDULED`
`IN_TRANSIT`
`AWAITING_CONFIRMATION`
`PARTIALLY_COMPLETED`
`QUEUED`
`SUSPENDED`
`DISPUTED`
`WRITTEN_OFF`
`ATTEMPTED`
`UNKNOWN`
`CAPTURED`
`SETTLEMENT_ERROR`

Blockchain Intel (shared)

BlockchainIntel

Field	Key	Type	Required	Description
Vendor	`vendor`	string enum value	Yes	Data provider identifier. Accepted: `chainalysis_kyt`
Vendor Version	`vendor_version`	string	Yes	Provider API version. E.g. `v2` or `v1`
Fetched At	`fetched_at`	string	Yes	ISO8601 datetime when the intel was retrieved from the provider
Data	`data`	object	Yes	Vendor-specific structured payload. Shape defined per `vendor` × `vendor_version` pair. Refer Blockchain->Data

data shape by context:

Attached to	vendor	Accepted versions	`data` shape
Transaction sender/receiver	`chainalysis_kyt`	`v2`	Transfer direct exposure — see "Transaction transfer exposure"
Entity	`chainalysis_kyt`	`v1`, `v2`	KYT user details — see "Entity KYT user details (v2 / v1)"

BlockchainIntel -> Data

Transaction transfer exposure (`chainalysis_kyt · v2`)

Used when blockchain_intel is attached to a transaction sender/receiver. data = the KYT direct-exposure response from GET /api/kyt/v2/transfers/{externalId}/exposures.

No result: send "direct": null to signal the lookup ran but returned nothing.

Field	Key	Type	Required	Description
Direct Name	`direct.name`	string	No	Identified counterparty name (e.g. `Binance`, `Tornado Cash`). Null if unknown
Direct Category ID	`direct.categoryId`	integer	No	Chainalysis numeric category ID

Entity KYT user details v2 (`chainalysis_kyt` · `v2`)

Used when blockchain_intel is attached to an entity. data = the KYT user-details response from GET /api/kyt/v2/users/{externalUserId}.

Field	Key	Data Type	Required	Description
User ID	`userId`	string	No	Chainalysis KYT user identifier
Risk Score	`riskScore`	string (enum)	No	`SEVERE` / `HIGH` / `MEDIUM` / `LOW`. Null if the user has no activity
Score Updated Date	`scoreUpdatedDate`	string	No	ISO8601 datetime when Chainalysis last updated the risk score
Created At	`createdAt`	string	No	ISO8601 datetime when the user was created in KYT
Last Activity	`lastActivity`	string	No	ISO8601 datetime timestamp of the user's most recent activity
Exposure Details	`exposureDetails`	array[KYTExposureDetail]	No	Per-category exposure breakdown (see KYTExposureDetail)
Properties	`properties`	object	No	`{ "active": boolean, "country": string }` (ISO 3166-1 alpha-2). v2 only

Entity KYT user details v1 (`chainalysis_kyt` · `v1`)

Used when blockchain_intel is attached to an entity with vendor_version: "v1". data = the response from GET /api/kyt/v1/users/{userId}. Same as v2 except: legacy score, creationDate instead of createdAt, and no properties.

Field	Key	Data Type	Required	Description
User ID	`userId`	string	No	Chainalysis KYT user identifier
Risk Score	`riskScore`	string (enum)	No	`SEVERE` / `HIGH` / `MEDIUM` / `LOW`. Null if no activity
Score (legacy)	`score`	string (enum)	No	`red` / `amber` / `green`. Legacy risk color, superseded by `riskScore`. v1 only
Score Updated Date	`scoreUpdatedDate`	string	No	ISO8601 datetime when the risk score was last updated
Creation Date	`creationDate`	string	No	ISO8601 datetime when the user was created in KYT (v1's equivalent of `createdAt`)
Last Activity	`lastActivity`	string	No	ISO8601 datetime of the user's most recent activity
Exposure Details	`exposureDetails`	array[KYTExposureDetail]	No	Per-category exposure breakdown (see KYTExposureDetail)

KYTExposureDetail

One entry per exposure category in exposureDetails (entity KYT user details, v1 and v2).

Field	Key	Data Type	Required	Description
Cluster	`cluster`	object	No	`{ "name": string, "categoryId": integer, "category": string }`. `category` (name string) is v1 only
Sent Direct Exposure	`sentDirectExposure`	float	No	USD value of direct exposure from funds sent
Sent Indirect Exposure	`sentIndirectExposure`	float	No	USD value of indirect exposure from funds sent
Received Direct Exposure	`receivedDirectExposure`	float	No	USD value of direct exposure from funds received
Received Indirect Exposure	`receivedIndirectExposure`	float	No	USD value of indirect exposure from funds received