--- title: "GET /v1/portfolios/{portfolioSlug}/transactions/{transactionId}" method: GET path: "/v1/portfolios/{portfolioSlug}/transactions/{transactionId}" tags: ["Portfolios"] --- # GET /v1/portfolios/{portfolioSlug}/transactions/{transactionId} `GET /v1/portfolios/{portfolioSlug}/transactions/{transactionId}` ## Request - Base URL: `https://api.tokenbooks.io` (the document declares no server; this is the origin it was published from) - URL: `https://api.tokenbooks.io/v1/portfolios/{portfolioSlug}/transactions/{transactionId}` - Auth: API key in header `x-api-key` ## Path parameters - `transactionId` string, required - `portfolioSlug` string, required ## Query parameters - `include` 'raw' | 'rawWithDetails': Optionally include contributing raw transactions. rawWithDetails returns sanitized details that may still contain untrusted provider-controlled content. ## Response `200` - union - PortfolioTransactionResponseDto - `id` string, required: Portfolio transaction ID - `operationType` string, required: Accounting operation type - `subType` string, nullable, required: Operation sub-type - `classification` object, required: Triage summary: classification state, reason, and suggested action - `state` 'categorized' | 'uncategorized' | 'error', required: Whether the transaction is categorized, uncategorized, or errored - `reason` string, nullable, required: Root failure mode (unwrapped), e.g. FmvNotAvailable; null if none - `detail` string, nullable, required: Human-readable detail for the primary issue, if any - `suggestedAction` object, nullable, required: Suggested remediation, if any - `tool` string, nullable, required: MCP tool to remediate with, or null if no single tool applies - `description` string, required: What to do to resolve it - `systemNotes` string, nullable, required: System-generated notes - `errorMessage` string, nullable, required: Legacy error message text if processing failed - `errorDetails` unknown[], nullable: Structured error details if processing failed - unknown - `timestamp` string, required: Transaction timestamp (ISO 8601) - `memo` string, nullable, required: User memo - `status` string, required: Transaction status - `tags` string[], required: Transaction tags - `fileAttachments` unknown[], required: Attached files metadata - unknown - `journalEntry` JournalEntryResponseDto, required - `id` string, required: Journal entry ID - `timestamp` string, required: Entry timestamp (ISO 8601) - `status` string, required: Journal entry status - `memo` string, nullable, required: User memo - `systemNotes` string, nullable, required: System-generated notes - `isAdjustment` boolean, required: Whether this is an adjustment entry - `portfolioTransactionId` string, nullable, required: Originating portfolio transaction ID, if any - `operationType` string, nullable, required: Operation type of the originating transaction - `subType` string, nullable, required: Operation sub-type of the originating transaction - `adjustmentJournalImportProvenance` object, nullable: Adjustment-import provenance with immutable file and source-row facts and the uploader's current display name, or null for a non-imported journal - `importRef` string, required - `sourceFile` object, required - `name` string, required - `uploadedAt` string, date-time, required - `uploader` object, required - `name` string, required - `sourceRows` object[], required - `appliedResolutions` object, required - `schemaVersion` 1, required - `values` object, required - `entryId` string, required - `journalLineNumber` integer, required - `locator` union, required - object - … - object - … - `normalizedValues` union, required - object - … - object - … - `sourceRowHash` string, required - `lines` object[], required: Debit/credit lines, ordered by line number - `lineNumber` integer, required: Line ordinal within the entry - `entryType` string, required: DR (debit) or CR (credit) - `accountName` string, nullable, required: Ledger account name - `accountNumber` string, nullable, required: Chart-of-accounts number - `accountType` string, nullable: Ledger account type - `accountSubType` string, nullable: Ledger account sub-type - `accountNormalBalanceType` string, nullable: Ledger account normal balance side - `fiatAmount` string, required: Fiat amount (decimal string) - `assetId` string, nullable, required: Asset ID when the line is asset-denominated - `assetSymbol` string, nullable, required: Asset symbol - `assetAmount` string, nullable, required: Asset quantity (decimal string) - `memo` string, nullable, required: Line memo - `responsibilityCenterAssignments` object[], required: Typed responsibility-center assignments, one per dimension, ordered by type sort order - `responsibilityCenterTypeId` string, required: Responsibility-center type ID used by edit commands - `responsibilityCenterId` string, required: Responsibility-center ID used by edit commands - `value` string, required: Filter-options-compatible public value for this assignment - `responsibilityCenterType` object, required: The dimension this assignment classifies the line under - `key` string, required: Stable type slug (e.g. primary, goal) - `name` string, required: Responsibility-center type name - `kind` 'COST' | 'REVENUE' | 'PROFIT' | 'INVESTMENT', required: Managerial taxonomy of the type - `responsibilityCenterName` string, required: Assigned responsibility-center name - `responsibilityCenterCode` string, nullable, required: Stable code of the center within its type, if any - `percentageBps` integer, required: Allocation in basis points (10000 = 100%) - `counterpartyName` string, nullable, required: Counterparty name - `lot` object, nullable, required: Cost-basis lot lineage when the line realizes gains/losses - `id` string, required: Lot identifier (e.g. BTC_001) - `entryId` string, required: Unique lot ledger entry ID - `entryKind` string, required: Lot entry kind (ADD, DSP, CUT, MVE, RES, REL) - `lotMethod` string, required: Lot accounting method (FIFO, LIFO, HIFO, ACB) - `transfer` object, nullable, required: Wallet transfer lineage when the line maps to an on-chain transfer - `txIndex` integer, nullable, required: Transfer index within the tx - `chainId` string, nullable, required: Chain ID of the transfer - `txHash` string, nullable, required: On-chain transaction hash - `walletOperations` object[], required: Wallet transfers that make up this transaction - `type` string, required: Transfer direction/type (e.g. IN, OUT) - `txHash` string, required: On-chain transaction hash - `chainId` string, required: Chain ID - `txIndex` integer, required: Transfer index within the transaction - `walletTransactionId` string, required: Wallet transaction handle for this operation; pair with txIndex to reference the operation in merge_transactions / split_transactions - `fromAddress` string, required: Sender address - `fromAddressLabel` string, nullable, required: Sender address label - `toAddress` string, required: Recipient address - `toAddressLabel` string, nullable, required: Recipient address label - `value` string, required: Human-readable transfer amount (decimal string) - `valueQuote` string, nullable, required: Fiat quote value (decimal string) - `quoteCurrency` string, nullable, required: Fiat quote currency - `quoteSource` string, nullable, required: Fiat quote source - `quoteMeta` object, nullable: Structured quote provenance, null when none is available, or temporarily omitted by an older server during a rolling deploy - `s` 'SYNC_SOURCE' | 'FMV_ENGINE' | 'DERIVED_REPRESENTED' | 'DERIVED_SIBLING' | 'POLICY' | 'MANUAL', required - `ts` integer - `assetId` string, nullable, required: Asset ID - `assetSymbol` string, nullable, required: Asset symbol - `tokenAddress` string, required: Token contract address - `isSpam` boolean, required: Effective spam flag (portfolio prefs applied) - `stablecoinPeggedFiatCurrency` string, nullable, required: Effective stablecoin peg, if any - `walletName` string, required: Owning wallet name - `walletAddress` string, required: Owning wallet address - `defiOperation` string, nullable, required: DeFi operation, if any - `defiPositionId` string, nullable, required: DeFi position ID, if any - `defiPositionRef` string, nullable: Stable DeFi position reference, if any - `walletSource` object, nullable: Wallet-backed source metadata for row actions - `wallet` object, required: Public wallet identity without internal wallet IDs - `chainId` string, required: Public chain ID of the wallet - `address` string, required: Public wallet address on the chain - `walletType` 'BLOCKCHAIN' | 'EXCHANGE' | 'BANK', required: Wallet type - `rawTransactionId` string, required: Wallet transaction ID - `rawTransactionSource` string, required: Wallet transaction source - `blockHeight` string, required: Wallet transaction block height as a decimal string - `timestamp` string, required: Wallet transaction timestamp serialized as ISO 8601 - `intercompanyPair` object, nullable: Intercompany pair metadata when this transaction is paired - `pairId` string, required: Intercompany move pair ID - `side` 'SEND' | 'RECEIVE', required: Whether this transaction is the sending or receiving side - `treatment` string, nullable, required: Applied intercompany treatment - `counterpartPortfolioName` string, required: Counterpart portfolio display name - `counterpartPortfolioSlug` string, required: Counterpart portfolio public slug - `counterpartPortfolioTransactionId` string, required: Counterpart portfolio transaction ID - `counterpartOperationType` string, required: Counterpart accounting operation type - `counterpartSubType` string, nullable, required: Counterpart accounting operation subtype - `counterpartStatus` 'PROPOSED' | 'ERROR' | 'POSTED' | 'CLOSED', required: Counterpart transaction status - `lotLinkCount` integer, required: Number of linked intercompany cost-basis lots - `portfolioTransactionContext` object, nullable: Flattened transaction context, when stored - PortfolioTransactionWithRawResponseDto - `id` string, required: Portfolio transaction ID - `operationType` string, required: Accounting operation type - `subType` string, nullable, required: Operation sub-type - `classification` object, required: Triage summary: classification state, reason, and suggested action - `state` 'categorized' | 'uncategorized' | 'error', required: Whether the transaction is categorized, uncategorized, or errored - `reason` string, nullable, required: Root failure mode (unwrapped), e.g. FmvNotAvailable; null if none - `detail` string, nullable, required: Human-readable detail for the primary issue, if any - `suggestedAction` object, nullable, required: Suggested remediation, if any - `tool` string, nullable, required: MCP tool to remediate with, or null if no single tool applies - `description` string, required: What to do to resolve it - `systemNotes` string, nullable, required: System-generated notes - `errorMessage` string, nullable, required: Legacy error message text if processing failed - `errorDetails` unknown[], nullable: Structured error details if processing failed - unknown - `timestamp` string, required: Transaction timestamp (ISO 8601) - `memo` string, nullable, required: User memo - `status` string, required: Transaction status - `tags` string[], required: Transaction tags - `fileAttachments` unknown[], required: Attached files metadata - unknown - `journalEntry` JournalEntryResponseDto, required - `id` string, required: Journal entry ID - `timestamp` string, required: Entry timestamp (ISO 8601) - `status` string, required: Journal entry status - `memo` string, nullable, required: User memo - `systemNotes` string, nullable, required: System-generated notes - `isAdjustment` boolean, required: Whether this is an adjustment entry - `portfolioTransactionId` string, nullable, required: Originating portfolio transaction ID, if any - `operationType` string, nullable, required: Operation type of the originating transaction - `subType` string, nullable, required: Operation sub-type of the originating transaction - `adjustmentJournalImportProvenance` object, nullable: Adjustment-import provenance with immutable file and source-row facts and the uploader's current display name, or null for a non-imported journal - `importRef` string, required - `sourceFile` object, required - `name` string, required - `uploadedAt` string, date-time, required - `uploader` object, required - `name` string, required - `sourceRows` object[], required - `appliedResolutions` object, required - `schemaVersion` 1, required - `values` object, required - `entryId` string, required - `journalLineNumber` integer, required - `locator` union, required - object - … - object - … - `normalizedValues` union, required - object - … - object - … - `sourceRowHash` string, required - `lines` object[], required: Debit/credit lines, ordered by line number - `lineNumber` integer, required: Line ordinal within the entry - `entryType` string, required: DR (debit) or CR (credit) - `accountName` string, nullable, required: Ledger account name - `accountNumber` string, nullable, required: Chart-of-accounts number - `accountType` string, nullable: Ledger account type - `accountSubType` string, nullable: Ledger account sub-type - `accountNormalBalanceType` string, nullable: Ledger account normal balance side - `fiatAmount` string, required: Fiat amount (decimal string) - `assetId` string, nullable, required: Asset ID when the line is asset-denominated - `assetSymbol` string, nullable, required: Asset symbol - `assetAmount` string, nullable, required: Asset quantity (decimal string) - `memo` string, nullable, required: Line memo - `responsibilityCenterAssignments` object[], required: Typed responsibility-center assignments, one per dimension, ordered by type sort order - `responsibilityCenterTypeId` string, required: Responsibility-center type ID used by edit commands - `responsibilityCenterId` string, required: Responsibility-center ID used by edit commands - `value` string, required: Filter-options-compatible public value for this assignment - `responsibilityCenterType` object, required: The dimension this assignment classifies the line under - `key` string, required: Stable type slug (e.g. primary, goal) - `name` string, required: Responsibility-center type name - `kind` 'COST' | 'REVENUE' | 'PROFIT' | 'INVESTMENT', required: Managerial taxonomy of the type - `responsibilityCenterName` string, required: Assigned responsibility-center name - `responsibilityCenterCode` string, nullable, required: Stable code of the center within its type, if any - `percentageBps` integer, required: Allocation in basis points (10000 = 100%) - `counterpartyName` string, nullable, required: Counterparty name - `lot` object, nullable, required: Cost-basis lot lineage when the line realizes gains/losses - `id` string, required: Lot identifier (e.g. BTC_001) - `entryId` string, required: Unique lot ledger entry ID - `entryKind` string, required: Lot entry kind (ADD, DSP, CUT, MVE, RES, REL) - `lotMethod` string, required: Lot accounting method (FIFO, LIFO, HIFO, ACB) - `transfer` object, nullable, required: Wallet transfer lineage when the line maps to an on-chain transfer - `txIndex` integer, nullable, required: Transfer index within the tx - `chainId` string, nullable, required: Chain ID of the transfer - `txHash` string, nullable, required: On-chain transaction hash - `walletOperations` object[], required: Wallet transfers that make up this transaction - `type` string, required: Transfer direction/type (e.g. IN, OUT) - `txHash` string, required: On-chain transaction hash - `chainId` string, required: Chain ID - `txIndex` integer, required: Transfer index within the transaction - `walletTransactionId` string, required: Wallet transaction handle for this operation; pair with txIndex to reference the operation in merge_transactions / split_transactions - `fromAddress` string, required: Sender address - `fromAddressLabel` string, nullable, required: Sender address label - `toAddress` string, required: Recipient address - `toAddressLabel` string, nullable, required: Recipient address label - `value` string, required: Human-readable transfer amount (decimal string) - `valueQuote` string, nullable, required: Fiat quote value (decimal string) - `quoteCurrency` string, nullable, required: Fiat quote currency - `quoteSource` string, nullable, required: Fiat quote source - `quoteMeta` object, nullable: Structured quote provenance, null when none is available, or temporarily omitted by an older server during a rolling deploy - `s` 'SYNC_SOURCE' | 'FMV_ENGINE' | 'DERIVED_REPRESENTED' | 'DERIVED_SIBLING' | 'POLICY' | 'MANUAL', required - `ts` integer - `assetId` string, nullable, required: Asset ID - `assetSymbol` string, nullable, required: Asset symbol - `tokenAddress` string, required: Token contract address - `isSpam` boolean, required: Effective spam flag (portfolio prefs applied) - `stablecoinPeggedFiatCurrency` string, nullable, required: Effective stablecoin peg, if any - `walletName` string, required: Owning wallet name - `walletAddress` string, required: Owning wallet address - `defiOperation` string, nullable, required: DeFi operation, if any - `defiPositionId` string, nullable, required: DeFi position ID, if any - `defiPositionRef` string, nullable: Stable DeFi position reference, if any - `walletSource` object, nullable: Wallet-backed source metadata for row actions - `wallet` object, required: Public wallet identity without internal wallet IDs - `chainId` string, required: Public chain ID of the wallet - `address` string, required: Public wallet address on the chain - `walletType` 'BLOCKCHAIN' | 'EXCHANGE' | 'BANK', required: Wallet type - `rawTransactionId` string, required: Wallet transaction ID - `rawTransactionSource` string, required: Wallet transaction source - `blockHeight` string, required: Wallet transaction block height as a decimal string - `timestamp` string, required: Wallet transaction timestamp serialized as ISO 8601 - `intercompanyPair` object, nullable: Intercompany pair metadata when this transaction is paired - `pairId` string, required: Intercompany move pair ID - `side` 'SEND' | 'RECEIVE', required: Whether this transaction is the sending or receiving side - `treatment` string, nullable, required: Applied intercompany treatment - `counterpartPortfolioName` string, required: Counterpart portfolio display name - `counterpartPortfolioSlug` string, required: Counterpart portfolio public slug - `counterpartPortfolioTransactionId` string, required: Counterpart portfolio transaction ID - `counterpartOperationType` string, required: Counterpart accounting operation type - `counterpartSubType` string, nullable, required: Counterpart accounting operation subtype - `counterpartStatus` 'PROPOSED' | 'ERROR' | 'POSTED' | 'CLOSED', required: Counterpart transaction status - `lotLinkCount` integer, required: Number of linked intercompany cost-basis lots - `portfolioTransactionContext` object, nullable: Flattened transaction context, when stored - `rawTransactions` RawTransactionCompleteDto[], required - `id` string, required: Operational current-row WalletTransaction UUID - `wallet` object, required - `chainId` string, required: Chain ID - `address` string, required: Wallet address - `name` string, nullable, required: Wallet display name - `type` 'BLOCKCHAIN' | 'EXCHANGE' | 'BANK', required: Wallet type - `hash` string, required - `blockHeight` string, required - `timestamp` string, date-time, required - `memo` string, nullable, required - `processingState` 'PROCESSED' | 'PARTIAL' | 'UNPROCESSED', required - `walletOperations` object[], required - `txIndex` integer, required - `type` 'IN' | 'OUT' | 'GAS' | 'SELF', required - `from` object, required - `address` string, required - `label` string, nullable, required - `to` object, required - `address` string, required - `label` string, nullable, required - `token` object, required - `chainId` string, required - `address` string, required - `assetId` string, required - `symbol` string, required - `type` union, required - 'ERC20': Standard fungible token with a freely transferable, free-floating balance. The default for the vast majority of tokens. Examples: USDC, UNI, LINK, and any plain ERC-20 (EVM) or fungible SPL (Solana) token that is not one of the more specific DeFi types below. - 'NATIVE': The chain's native gas asset, used to pay transaction fees and not represented by a token contract. Examples: ETH on Ethereum, SOL on Solana, MATIC on Polygon, TRX on Tron, NEAR on NEAR. The wrapped form (e.g. WETH, wSOL) is a separate ERC20/NATIVE token linked by representation metadata, not this value. - 'FIAT': Off-chain fiat currency balance rather than an on-chain token. Examples: a USD, EUR, or GBP cash balance held on a centralized exchange or bank account. - 'NFT': Non-fungible token. Stored as one Token row per (contract, tokenId) with address `${contractAddress}#${tokenId}`. Examples: a Uniswap v3 concentrated-liquidity position NFT, or an art/PFP collectible. An NFT may still be a DeFi position container (e.g. a Uniswap v3 LP NFT); the position itself is modeled separately. - 'REBASE_LST': Rebasing liquid-staking token: the holder BALANCE grows over time to distribute staking rewards while the token stays ~1:1 pegged to the staked asset (balance-growing mechanic, staking domain). Example: stETH (Lido), where balanceOf increases each day with no incoming transfer. Contrast VALUE_ACCRUING for the wrapped, non-rebasing form (e.g. wstETH) that keeps a fixed balance and accrues via an exchange rate. - 'INTEREST_BEARING': Interest-bearing lending receipt whose holder BALANCE grows continuously at ~1:1 with the supplied underlying (Aave-style scaled balance multiplied by a rising liquidity index; balance-growing mechanic, lending domain). Examples: Aave aTokens such as aUSDC and aWETH, where your aUSDC quantity increases as interest accrues and 1 aUSDC always redeems for ~1 USDC. Mechanically the same balance-growth shape as REBASE_LST but for a lending deposit rather than staking. Contrast VALUE_ACCRUING for Compound cTokens, which instead keep a fixed balance and appreciate via an exchange rate. - 'VALUE_ACCRUING': Value-accruing receipt or share: the holder BALANCE is fixed and each unit becomes redeemable for a rising amount of a single underlying via an on-chain exchange rate (value-accruing mechanic). Examples: ERC-4626 vault shares (Yearn v3, Morpho), Beefy `moo*` vault shares (the core `BeefyVaultV7` is NOT ERC-4626 — it exposes `want()` and `getPricePerFullShare()` where a 4626 vault would expose `asset()` and `convertToAssets()`), Compound cTokens, wrapped LSTs (wstETH, rETH, cbETH, sfrxETH), and Solana LSTs (mSOL, JitoSOL). The represented underlying is usually discoverable on-chain (e.g. ERC-4626 `asset()`), but the exchange RATE is a time-varying derived value and must not be stored as a fixed ratio. Contrast INTEREST_BEARING and REBASE_LST, where the balance grows instead. - 'LP_SHARE': Liquidity-pool share representing proportional ownership of a BASKET of two or more pooled underlyings, so it has no single represented underlying token. Examples: Uniswap v2 pair tokens, Curve LP tokens, Balancer BPT, PancakeSwap LP tokens, Raydium/Orca LP tokens. A single-underlying receipt is VALUE_ACCRUING; a multi-underlying pool token is LP_SHARE. - 'DEBT': Non-transferable borrow or liability marker. The balance equals the amount owed (principal plus accrued interest) and is booked on the liability side, never as an asset. Examples: Aave variable and stable debt tokens such as variableDebtUSDC. Transfers and approvals typically revert, so it is a position record exposed as a token rather than a tradeable token. - 'REFLECT': Reflection / redistribution token: holder balances change via a fee-redistribution rate shift rather than via transfers (reflect.finance forks). Example: SAFEMOON-style tokens that redistribute a transfer tax to all holders. - 'VOTE_ESCROWED': Vote-escrowed lock position, typically non-transferable, created by locking a governance token for a fixed duration to receive boosted rewards or voting power. Examples: veCRV (Curve), veBAL (Balancer). - `decimals` integer, required - `isSpam` boolean, required - `stablecoinPeggedFiatCurrency` string, nullable, required - `representsTokenAddress` string, nullable, required - `value` string, required: Precise signed decimal value encoded as a string. - `quote` object, nullable, required - `value` string, nullable, required: Precise signed decimal value encoded as a string. - `currency` string, nullable, required - `source` string, nullable, required - `meta` object, nullable, required - `s` 'SYNC_SOURCE' | 'FMV_ENGINE' | 'DERIVED_REPRESENTED' | 'DERIVED_SIBLING' | 'POLICY' | 'MANUAL', required - `ts` integer - `defi` object, nullable, required - `operation` union, required - 'PROTOCOL_DEPOSIT': Deposit assets into protocol-managed custody without immediate disposal - 'PROTOCOL_WITHDRAW': Withdraw assets from protocol-managed custody back to the wallet - 'VAULT_DEPOSIT': Deposit into a tokenized vault: one underlying is pooled under a manager or strategy and the depositor receives a fungible share - 'VAULT_WITHDRAW': Redemption from a tokenized vault: share burned, underlying returned - 'SWAP': Token swap/exchange on DEX (e.g., ETH → USDC on Uniswap) - 'PROVIDE_LIQUIDITY': Add tokens to liquidity pool (e.g., add ETH+USDC to Uniswap pool) - 'REMOVE_LIQUIDITY': Remove tokens from liquidity pool (e.g., withdraw from Uniswap pool) - 'LEND': Supply tokens to lending protocol (e.g., deposit USDC to Aave) - 'WITHDRAW_LEND': Withdraw supplied tokens from lending protocol (e.g., withdraw USDC from Aave) - 'LEND_REDUCE': Reduce supplied lending exposure without receiving underlying back to the wallet - 'BORROW': Borrow tokens from lending protocol (e.g., borrow ETH from Aave) - 'REPAY': Repay borrowed tokens to lending protocol - 'LOAN_LIQUIDATION': Forced loan liquidation that reduces protocol debt and seizes collateral - 'STAKE': Stake tokens for rewards (e.g., stake ETH for staking rewards) - 'UNSTAKE': Unstake tokens from staking protocol - 'CLAIM_REWARDS': Claim earned rewards from staking, LP fees, or other yield sources - `tokenRole` union, required - 'UNDERLYING': The base/principal asset moving into or out of a position: the asset supplied, withdrawn, borrowed, repaid, staked, or unstaked, and the actual asset paid when reducing a debt. This is the real asset, not a receipt or marker for it. Examples: the ETH leg of a stake, or the USDC leg paid to repay an Aave loan. Processors read the repaid/supplied asset id from this leg. - 'COLLATERAL': An asset posted or locked as collateral, or seized as collateral during a liquidation, as distinct from a plain principal deposit. Role is per-transfer, so the same token can be UNDERLYING in one transfer and COLLATERAL in another. Example: the collateral (often an aToken or its underlying) taken from a borrower in an Aave V3 liquidation. - 'RECEIPT_TOKEN': A token that represents a claim on a supplied or staked position (a receipt or share) rather than the underlying itself. Covers interest-bearing receipts and value-accruing shares regardless of mechanic. Examples: Aave aTokens (aUSDC), Compound cTokens, JustLend jTokens, ERC-4626 vault shares, liquid-staking receipts. Whether it rebases or accrues via an exchange rate is captured by the token TokenType, not by this role. - 'LP_SHARE': A liquidity-pool share representing proportional ownership of a basket of two or more pooled underlyings. Examples: Uniswap v2 pair tokens, Curve and Balancer LP tokens, a Uniswap v3 concentrated-liquidity position NFT. - 'LIABILITY_TOKEN': A borrow/debt marker representing an outstanding liability (principal plus accrued interest), typically non-transferable. Examples: Aave variable and stable debt tokens (variableDebtUSDC). It must be booked on the liability side and is structurally distinct from a RECEIPT_TOKEN (asset side), so the two never share one value. Lets processors identify the debt leg by role instead of matching `variableDebt`/`stableDebt` symbol prefixes. - 'REWARD': An incentive, yield, or fee-share token realized from a position separately from principal. Examples: claimed governance/incentive tokens, or accrued trading-fee rewards. - 'OTHER': A protocol-specific or not-yet-classified token leg that does not fit the roles above. Use sparingly; prefer adding a generic role once a pattern recurs across protocols. - `positionRef` string, nullable, required - `portfolioTransactionId` string, nullable, required - PortfolioTransactionWithRawDetailsResponseDto - `id` string, required: Portfolio transaction ID - `operationType` string, required: Accounting operation type - `subType` string, nullable, required: Operation sub-type - `classification` object, required: Triage summary: classification state, reason, and suggested action - `state` 'categorized' | 'uncategorized' | 'error', required: Whether the transaction is categorized, uncategorized, or errored - `reason` string, nullable, required: Root failure mode (unwrapped), e.g. FmvNotAvailable; null if none - `detail` string, nullable, required: Human-readable detail for the primary issue, if any - `suggestedAction` object, nullable, required: Suggested remediation, if any - `tool` string, nullable, required: MCP tool to remediate with, or null if no single tool applies - `description` string, required: What to do to resolve it - `systemNotes` string, nullable, required: System-generated notes - `errorMessage` string, nullable, required: Legacy error message text if processing failed - `errorDetails` unknown[], nullable: Structured error details if processing failed - unknown - `timestamp` string, required: Transaction timestamp (ISO 8601) - `memo` string, nullable, required: User memo - `status` string, required: Transaction status - `tags` string[], required: Transaction tags - `fileAttachments` unknown[], required: Attached files metadata - unknown - `journalEntry` JournalEntryResponseDto, required - `id` string, required: Journal entry ID - `timestamp` string, required: Entry timestamp (ISO 8601) - `status` string, required: Journal entry status - `memo` string, nullable, required: User memo - `systemNotes` string, nullable, required: System-generated notes - `isAdjustment` boolean, required: Whether this is an adjustment entry - `portfolioTransactionId` string, nullable, required: Originating portfolio transaction ID, if any - `operationType` string, nullable, required: Operation type of the originating transaction - `subType` string, nullable, required: Operation sub-type of the originating transaction - `adjustmentJournalImportProvenance` object, nullable: Adjustment-import provenance with immutable file and source-row facts and the uploader's current display name, or null for a non-imported journal - `importRef` string, required - `sourceFile` object, required - `name` string, required - `uploadedAt` string, date-time, required - `uploader` object, required - `name` string, required - `sourceRows` object[], required - `appliedResolutions` object, required - `schemaVersion` 1, required - `values` object, required - `entryId` string, required - `journalLineNumber` integer, required - `locator` union, required - object - … - object - … - `normalizedValues` union, required - object - … - object - … - `sourceRowHash` string, required - `lines` object[], required: Debit/credit lines, ordered by line number - `lineNumber` integer, required: Line ordinal within the entry - `entryType` string, required: DR (debit) or CR (credit) - `accountName` string, nullable, required: Ledger account name - `accountNumber` string, nullable, required: Chart-of-accounts number - `accountType` string, nullable: Ledger account type - `accountSubType` string, nullable: Ledger account sub-type - `accountNormalBalanceType` string, nullable: Ledger account normal balance side - `fiatAmount` string, required: Fiat amount (decimal string) - `assetId` string, nullable, required: Asset ID when the line is asset-denominated - `assetSymbol` string, nullable, required: Asset symbol - `assetAmount` string, nullable, required: Asset quantity (decimal string) - `memo` string, nullable, required: Line memo - `responsibilityCenterAssignments` object[], required: Typed responsibility-center assignments, one per dimension, ordered by type sort order - `responsibilityCenterTypeId` string, required: Responsibility-center type ID used by edit commands - `responsibilityCenterId` string, required: Responsibility-center ID used by edit commands - `value` string, required: Filter-options-compatible public value for this assignment - `responsibilityCenterType` object, required: The dimension this assignment classifies the line under - `key` string, required: Stable type slug (e.g. primary, goal) - `name` string, required: Responsibility-center type name - `kind` 'COST' | 'REVENUE' | 'PROFIT' | 'INVESTMENT', required: Managerial taxonomy of the type - `responsibilityCenterName` string, required: Assigned responsibility-center name - `responsibilityCenterCode` string, nullable, required: Stable code of the center within its type, if any - `percentageBps` integer, required: Allocation in basis points (10000 = 100%) - `counterpartyName` string, nullable, required: Counterparty name - `lot` object, nullable, required: Cost-basis lot lineage when the line realizes gains/losses - `id` string, required: Lot identifier (e.g. BTC_001) - `entryId` string, required: Unique lot ledger entry ID - `entryKind` string, required: Lot entry kind (ADD, DSP, CUT, MVE, RES, REL) - `lotMethod` string, required: Lot accounting method (FIFO, LIFO, HIFO, ACB) - `transfer` object, nullable, required: Wallet transfer lineage when the line maps to an on-chain transfer - `txIndex` integer, nullable, required: Transfer index within the tx - `chainId` string, nullable, required: Chain ID of the transfer - `txHash` string, nullable, required: On-chain transaction hash - `walletOperations` object[], required: Wallet transfers that make up this transaction - `type` string, required: Transfer direction/type (e.g. IN, OUT) - `txHash` string, required: On-chain transaction hash - `chainId` string, required: Chain ID - `txIndex` integer, required: Transfer index within the transaction - `walletTransactionId` string, required: Wallet transaction handle for this operation; pair with txIndex to reference the operation in merge_transactions / split_transactions - `fromAddress` string, required: Sender address - `fromAddressLabel` string, nullable, required: Sender address label - `toAddress` string, required: Recipient address - `toAddressLabel` string, nullable, required: Recipient address label - `value` string, required: Human-readable transfer amount (decimal string) - `valueQuote` string, nullable, required: Fiat quote value (decimal string) - `quoteCurrency` string, nullable, required: Fiat quote currency - `quoteSource` string, nullable, required: Fiat quote source - `quoteMeta` object, nullable: Structured quote provenance, null when none is available, or temporarily omitted by an older server during a rolling deploy - `s` 'SYNC_SOURCE' | 'FMV_ENGINE' | 'DERIVED_REPRESENTED' | 'DERIVED_SIBLING' | 'POLICY' | 'MANUAL', required - `ts` integer - `assetId` string, nullable, required: Asset ID - `assetSymbol` string, nullable, required: Asset symbol - `tokenAddress` string, required: Token contract address - `isSpam` boolean, required: Effective spam flag (portfolio prefs applied) - `stablecoinPeggedFiatCurrency` string, nullable, required: Effective stablecoin peg, if any - `walletName` string, required: Owning wallet name - `walletAddress` string, required: Owning wallet address - `defiOperation` string, nullable, required: DeFi operation, if any - `defiPositionId` string, nullable, required: DeFi position ID, if any - `defiPositionRef` string, nullable: Stable DeFi position reference, if any - `walletSource` object, nullable: Wallet-backed source metadata for row actions - `wallet` object, required: Public wallet identity without internal wallet IDs - `chainId` string, required: Public chain ID of the wallet - `address` string, required: Public wallet address on the chain - `walletType` 'BLOCKCHAIN' | 'EXCHANGE' | 'BANK', required: Wallet type - `rawTransactionId` string, required: Wallet transaction ID - `rawTransactionSource` string, required: Wallet transaction source - `blockHeight` string, required: Wallet transaction block height as a decimal string - `timestamp` string, required: Wallet transaction timestamp serialized as ISO 8601 - `intercompanyPair` object, nullable: Intercompany pair metadata when this transaction is paired - `pairId` string, required: Intercompany move pair ID - `side` 'SEND' | 'RECEIVE', required: Whether this transaction is the sending or receiving side - `treatment` string, nullable, required: Applied intercompany treatment - `counterpartPortfolioName` string, required: Counterpart portfolio display name - `counterpartPortfolioSlug` string, required: Counterpart portfolio public slug - `counterpartPortfolioTransactionId` string, required: Counterpart portfolio transaction ID - `counterpartOperationType` string, required: Counterpart accounting operation type - `counterpartSubType` string, nullable, required: Counterpart accounting operation subtype - `counterpartStatus` 'PROPOSED' | 'ERROR' | 'POSTED' | 'CLOSED', required: Counterpart transaction status - `lotLinkCount` integer, required: Number of linked intercompany cost-basis lots - `portfolioTransactionContext` object, nullable: Flattened transaction context, when stored - `rawTransactions` object[], required - `id` string, required: Operational current-row WalletTransaction UUID - `wallet` object, required - `chainId` string, required: Chain ID - `address` string, required: Wallet address - `name` string, nullable, required: Wallet display name - `type` 'BLOCKCHAIN' | 'EXCHANGE' | 'BANK', required: Wallet type - `hash` string, required - `blockHeight` string, required - `timestamp` string, date-time, required - `memo` string, nullable, required - `processingState` 'PROCESSED' | 'PARTIAL' | 'UNPROCESSED', required - `walletOperations` object[], required - `txIndex` integer, required - `type` 'IN' | 'OUT' | 'GAS' | 'SELF', required - `from` object, required - `address` string, required - `label` string, nullable, required - `to` object, required - `address` string, required - `label` string, nullable, required - `token` object, required - `chainId` string, required - `address` string, required - `assetId` string, required - `symbol` string, required - `type` union, required - 'ERC20': Standard fungible token with a freely transferable, free-floating balance. The default for the vast majority of tokens. Examples: USDC, UNI, LINK, and any plain ERC-20 (EVM) or fungible SPL (Solana) token that is not one of the more specific DeFi types below. - 'NATIVE': The chain's native gas asset, used to pay transaction fees and not represented by a token contract. Examples: ETH on Ethereum, SOL on Solana, MATIC on Polygon, TRX on Tron, NEAR on NEAR. The wrapped form (e.g. WETH, wSOL) is a separate ERC20/NATIVE token linked by representation metadata, not this value. - 'FIAT': Off-chain fiat currency balance rather than an on-chain token. Examples: a USD, EUR, or GBP cash balance held on a centralized exchange or bank account. - 'NFT': Non-fungible token. Stored as one Token row per (contract, tokenId) with address `${contractAddress}#${tokenId}`. Examples: a Uniswap v3 concentrated-liquidity position NFT, or an art/PFP collectible. An NFT may still be a DeFi position container (e.g. a Uniswap v3 LP NFT); the position itself is modeled separately. - 'REBASE_LST': Rebasing liquid-staking token: the holder BALANCE grows over time to distribute staking rewards while the token stays ~1:1 pegged to the staked asset (balance-growing mechanic, staking domain). Example: stETH (Lido), where balanceOf increases each day with no incoming transfer. Contrast VALUE_ACCRUING for the wrapped, non-rebasing form (e.g. wstETH) that keeps a fixed balance and accrues via an exchange rate. - 'INTEREST_BEARING': Interest-bearing lending receipt whose holder BALANCE grows continuously at ~1:1 with the supplied underlying (Aave-style scaled balance multiplied by a rising liquidity index; balance-growing mechanic, lending domain). Examples: Aave aTokens such as aUSDC and aWETH, where your aUSDC quantity increases as interest accrues and 1 aUSDC always redeems for ~1 USDC. Mechanically the same balance-growth shape as REBASE_LST but for a lending deposit rather than staking. Contrast VALUE_ACCRUING for Compound cTokens, which instead keep a fixed balance and appreciate via an exchange rate. - 'VALUE_ACCRUING': Value-accruing receipt or share: the holder BALANCE is fixed and each unit becomes redeemable for a rising amount of a single underlying via an on-chain exchange rate (value-accruing mechanic). Examples: ERC-4626 vault shares (Yearn v3, Morpho), Beefy `moo*` vault shares (the core `BeefyVaultV7` is NOT ERC-4626 — it exposes `want()` and `getPricePerFullShare()` where a 4626 vault would expose `asset()` and `convertToAssets()`), Compound cTokens, wrapped LSTs (wstETH, rETH, cbETH, sfrxETH), and Solana LSTs (mSOL, JitoSOL). The represented underlying is usually discoverable on-chain (e.g. ERC-4626 `asset()`), but the exchange RATE is a time-varying derived value and must not be stored as a fixed ratio. Contrast INTEREST_BEARING and REBASE_LST, where the balance grows instead. - 'LP_SHARE': Liquidity-pool share representing proportional ownership of a BASKET of two or more pooled underlyings, so it has no single represented underlying token. Examples: Uniswap v2 pair tokens, Curve LP tokens, Balancer BPT, PancakeSwap LP tokens, Raydium/Orca LP tokens. A single-underlying receipt is VALUE_ACCRUING; a multi-underlying pool token is LP_SHARE. - 'DEBT': Non-transferable borrow or liability marker. The balance equals the amount owed (principal plus accrued interest) and is booked on the liability side, never as an asset. Examples: Aave variable and stable debt tokens such as variableDebtUSDC. Transfers and approvals typically revert, so it is a position record exposed as a token rather than a tradeable token. - 'REFLECT': Reflection / redistribution token: holder balances change via a fee-redistribution rate shift rather than via transfers (reflect.finance forks). Example: SAFEMOON-style tokens that redistribute a transfer tax to all holders. - 'VOTE_ESCROWED': Vote-escrowed lock position, typically non-transferable, created by locking a governance token for a fixed duration to receive boosted rewards or voting power. Examples: veCRV (Curve), veBAL (Balancer). - `decimals` integer, required - `isSpam` boolean, required - `stablecoinPeggedFiatCurrency` string, nullable, required - `representsTokenAddress` string, nullable, required - `value` string, required: Precise signed decimal value encoded as a string. - `quote` object, nullable, required - `value` string, nullable, required: Precise signed decimal value encoded as a string. - `currency` string, nullable, required - `source` string, nullable, required - `meta` object, nullable, required - `s` 'SYNC_SOURCE' | 'FMV_ENGINE' | 'DERIVED_REPRESENTED' | 'DERIVED_SIBLING' | 'POLICY' | 'MANUAL', required - `ts` integer - `defi` object, nullable, required - `operation` union, required - 'PROTOCOL_DEPOSIT': Deposit assets into protocol-managed custody without immediate disposal - 'PROTOCOL_WITHDRAW': Withdraw assets from protocol-managed custody back to the wallet - 'VAULT_DEPOSIT': Deposit into a tokenized vault: one underlying is pooled under a manager or strategy and the depositor receives a fungible share - 'VAULT_WITHDRAW': Redemption from a tokenized vault: share burned, underlying returned - 'SWAP': Token swap/exchange on DEX (e.g., ETH → USDC on Uniswap) - 'PROVIDE_LIQUIDITY': Add tokens to liquidity pool (e.g., add ETH+USDC to Uniswap pool) - 'REMOVE_LIQUIDITY': Remove tokens from liquidity pool (e.g., withdraw from Uniswap pool) - 'LEND': Supply tokens to lending protocol (e.g., deposit USDC to Aave) - 'WITHDRAW_LEND': Withdraw supplied tokens from lending protocol (e.g., withdraw USDC from Aave) - 'LEND_REDUCE': Reduce supplied lending exposure without receiving underlying back to the wallet - 'BORROW': Borrow tokens from lending protocol (e.g., borrow ETH from Aave) - 'REPAY': Repay borrowed tokens to lending protocol - 'LOAN_LIQUIDATION': Forced loan liquidation that reduces protocol debt and seizes collateral - 'STAKE': Stake tokens for rewards (e.g., stake ETH for staking rewards) - 'UNSTAKE': Unstake tokens from staking protocol - 'CLAIM_REWARDS': Claim earned rewards from staking, LP fees, or other yield sources - `tokenRole` union, required - 'UNDERLYING': The base/principal asset moving into or out of a position: the asset supplied, withdrawn, borrowed, repaid, staked, or unstaked, and the actual asset paid when reducing a debt. This is the real asset, not a receipt or marker for it. Examples: the ETH leg of a stake, or the USDC leg paid to repay an Aave loan. Processors read the repaid/supplied asset id from this leg. - 'COLLATERAL': An asset posted or locked as collateral, or seized as collateral during a liquidation, as distinct from a plain principal deposit. Role is per-transfer, so the same token can be UNDERLYING in one transfer and COLLATERAL in another. Example: the collateral (often an aToken or its underlying) taken from a borrower in an Aave V3 liquidation. - 'RECEIPT_TOKEN': A token that represents a claim on a supplied or staked position (a receipt or share) rather than the underlying itself. Covers interest-bearing receipts and value-accruing shares regardless of mechanic. Examples: Aave aTokens (aUSDC), Compound cTokens, JustLend jTokens, ERC-4626 vault shares, liquid-staking receipts. Whether it rebases or accrues via an exchange rate is captured by the token TokenType, not by this role. - 'LP_SHARE': A liquidity-pool share representing proportional ownership of a basket of two or more pooled underlyings. Examples: Uniswap v2 pair tokens, Curve and Balancer LP tokens, a Uniswap v3 concentrated-liquidity position NFT. - 'LIABILITY_TOKEN': A borrow/debt marker representing an outstanding liability (principal plus accrued interest), typically non-transferable. Examples: Aave variable and stable debt tokens (variableDebtUSDC). It must be booked on the liability side and is structurally distinct from a RECEIPT_TOKEN (asset side), so the two never share one value. Lets processors identify the debt leg by role instead of matching `variableDebt`/`stableDebt` symbol prefixes. - 'REWARD': An incentive, yield, or fee-share token realized from a position separately from principal. Examples: claimed governance/incentive tokens, or accrued trading-fee rewards. - 'OTHER': A protocol-specific or not-yet-classified token leg that does not fit the roles above. Use sparingly; prefer adding a generic role once a pattern recurs across protocols. - `positionRef` string, nullable, required - `portfolioTransactionId` string, nullable, required - `details` union, required - string - number - boolean - unknown - PortfolioTransactionWithRawDetailsResponseDtoSchema0[], nullable - object, nullable ## Other responses - `400`: Raw transaction details cannot be returned safely. Omit include or use include=raw. --- [API](https://skmtc.dev/tokenbooks/apis/tokenbooks-public-api.md) · [All operations](https://skmtc.dev/tokenbooks/apis/tokenbooks-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenbooks/apis/tokenbooks-public-api/revisions/180622e6255e?raw)