The TaxBit Transaction Data Model (TDM) is the format TaxBit expects transaction data in the /transaction/ POST, and File Exchange to be inserted into our transaction database.

Field Name	Data Type	Required	Description
`user_id`	`<UUID>`	✅	Unique UUID for the user who executed the transaction. Read more about the user model here.
`id`	`<string>`	✅	Unique external id for the transaction provided by the client.
`metadata`	`Metadata`	❌	Map of Metadata Objects. This contains the blockchain and transaction hash information along with other fields.
`datetime`	iso 8601 formatted `<string>`	✅	Datetime at which the transaction was executed. Formatted YYYY-MM-DDTHH:mm:ss.SSSZ
`type`	`<string>` enum	✅	Transaction types enum: [`trade`, `deposit`, `withdraw`, `income`, `expense`] This field determines the tax treatment for the transaction.
`subtype`	`<string>` enum	❌	Has no impact on tax calculations but is used to describe the transaction further than the type alone. Specific subtypes might only be valid with specific types. Supported sub-types: `income`: ['interest-crypto-backed', 'interest-fiat-backed', 'royalties','rent','gross-proceeds-paid-to-an-attorney','nec','payment-goods', payment-services' 'other','airdrop','reward','staking-reward','medical-payment','referral-bonus'] `expense`: ['debit'] `deposit`: ['ach','blockchain','card-reward','cost-basis-fmv'] `withdraw`: ['ach','blockchain'] `trade`: []
`fees`	`[LineItem]`	❌	An array of the LineItem Objects representing the fees paid by the user.
`received`	`[LineItem]`	Trade: ✅ Deposit: ✅ Withdraw: ❌ Income: ✅ Expense: ❌	An array of the LineItem Object's amounts received by the user as part of the transaction. Note: Received AmountObjects should be exclusive of fees.
`sent`	`[LineItem]`	Trade: ✅ Deposit: ❌ Withdraw: ✅ Income: ❌ Expense: ✅	An array of the LineItem Object's amounts sent by the user as part of the transaction. Note: Sent AmountObjects should be exclusive of fees.
`version`	`<string>`	✅	Data model version. Currently, only 1.0.

Metadata Object

Field Name	Data Type	Required	Description
`platform`	`Platform`	❌	Platform Object. Contains the name of the blockchain and the transaction hash associated with it. The platform object is required for transactions of type 'deposit' and 'withdraw' when subtype is 'blockchain'.
`TBD`	`<string>`	❌	Additional fields can be added per client needs

Platform Object

📘
NOTE: The platform object is only required for transactions of type 'deposit' or 'withdraw' and subtype 'blockchain'.

Field Name	Data Type	Required	Description
`transaction_hash`	`<string>`	✅	The transaction hash. Example: `fb4453744c33b2e7e86cb234152b021ecd089086be2acd4195e398b370005ab8`
`network`	`<string>`	❌	The blockchain/network that the transaction executed on. Example: `Bitcoin`
`from_addresses`	`[<string>]`	❌	The address Example: `[bc1qsr8hgdd7dnywrt3qudjhnvueywylnfa97sj0k5]`
`to_addresses`	`[<string>]`	Trade: ❌ Deposit: ✅ Withdraw: ✅ Income: ❌ Expense: ❌	The address Example: `[3NemmhVYmpL1rhenRQGsEbkN14yKV28HrW]` Note: To participate in Cost Basis Interchange, this field is required.

LineItem Object

Field Name	Data Type	Required	Description
`asset_amount`	`AssetAmount`	✅	AssetAmount Object
`rates`	[`AssetAmount`]	✅	An array of AssetAmount Object's that represent the fair market value of the asset denominated in the local fiat currency of the user’s tax jurisdiction(s)

AssetAmount Object

Field Name	Data Type	Required	Description
`amount`	`<string>`	✅	The decimal amount of the asset is a string.
`asset`	`Asset`	✅	Asset Object

Asset Object

Field Name	Data Type	Required	Description
`code`	`<string>`	✅	The code for the asset. Examples: `BTC`, `ETH`, `USD`
`type`	`<string>`	✅	The type of the asset. Valid Types: `crypto`, `fiat`, `preciousmetal`

Examples

Primitive Types:

Trade
Deposit
Withdraw
Income
Expense

Trade

A trade is an exchange of one asset for another. A trade is inclusive of buying digital assets or selling digital assets with fiat or swapping digital assets for other digital assets.

📘
NOTE: Trade transactions should not have a subtype field.

`Trade` Example

{
	"user_id": "UUID",
	"id": "<string>",
	"datetime": "2020-06-23T15:59:21.000Z",
	"type": "trade",
	"fees": [{
		"asset_amount": {
			"amount": "0.001",
			"asset": {
				"code": "BTC",
				"type": "crypto"
			}
		},
		"rates": [{
			"amount": "9090.91",
			"asset": {
				"code": "USD",
				"type": "fiat"
			}
		}]
	}],
	"received": [{
		"asset_amount": {
			"amount": "0.022",
			"asset": {
				"code": "BTC",
				"type": "crypto"
			}
		},
		"rates": [{
			"amount": "9090.91",
			"asset": {
				"code": "USD",
				"type": "fiat"
			}
		}]
	}],
	"sent": [{
		"asset_amount": {
			"amount": "200",
			"asset": {
				"code": "GUSD",
				"type": "crypto"
			}
		},
		"rates": [{
			"amount": "1.00",
			"asset": {
				"code": "USD",
				"type": "fiat"
			}
		}]
	}],
	"version": "1.0"
}

Deposit

This is the transaction type for transfers onto the exchange. This may include crypto or fiat.

The subtype field is to specify the type of transfer. Some possible options include: blockchain, ach, and wire.

📘
NOTE: For blockchain Deposits and Withdraw transactions, both the platform and subtype fields are required.

`Blockchain` Deposit Example

{
    "user_id": "UUID",
    "id": "<string>",
    "metadata": {
        "platform": {
            "transaction_hash": "fb4453744c33b2e7e86cb234152b021ecd089086be2acd4195e398b370005ab8",
            "network": "Bitcoin", // name of the blockchain
            "from_addresses": ["bc1qsr8hgdd7dnywrt3qudjhnvueywylnfa97sj0k5"],
            "to_addresses": ["3NemmhVYmpL1rhenRQGsEbkN14yKV28HrW"]
        }
    },
    "datetime": "2020-06-23T15:59:21.000Z", // datetime of when the funds became available to trade
    "type": "deposit",
    "subtype": "blockchain",
    "received": [{
        "asset_amount": {
            "amount": "0.5", 
            "asset": {
                "code": "BTC",
                "type": "crypto"
            }
        },
        "rates": [{
            "amount": "58000",
            "asset": {
                "code": "USD",
                "type": "fiat" // must be fiat
            }
        }]
    }],
    "version": "1.0"
}

`ACH Deposit` Example

{
	"user_id": "UUID",
	"id": "<string>",
	"datetime": "2020-06-23T15:59:21.000Z", // datetime of when the funds became available to trade
	"type": "deposit",
	"subtype": "ach",
	"received": [{
		"asset_amount": {
			"amount": "100.00",
			"asset": {
				"code": "USD",
				"type": "fiat"
			}
		},
		"rates": [{
			"amount": "1.00",
			"asset": {
				"code": "USD",
				"type": "fiat" // must be fiat
			}
		}]
	}],
	"version": "1.0"
}

Withdraw

This is the transaction type for transfers off the exchange. This may include crypto or fiat.

The subtype field is to specify the type of transfer. Some possible options include: blockchain, ach, and wire.

`Blockchain Withdraw` Example

{
    "user_id": "UUID",
    "id": "<string>",
    "metadata": {
        "platform": {
            "transaction_hash": "fb4453744c33b2e7e86cb234152b021ecd089086be2acd4195e398b370005ab8",
            "network": "Bitcoin", // name of the blockchain
            "from_addresses": ["bc1qsr8hgdd7dnywrt3qudjhnvueywylnfa97sj0k5"],
            "to_addresses": ["3NemmhVYmpL1rhenRQGsEbkN14yKV28HrW"]
        }
    },
    "datetime": "2020-06-23T15:59:21.000Z", // the datetime the transaction was confirmed
    "type": "withdraw",
    "subtype": "blockchain",
    "fees": [{
        "asset_amount": {
            "amount": "0.00007336",
            "asset": {
                "code": "BTC",
                "type": "crypto"
            }
        },
        "rates": [{
            "amount": "36697.25",
            "asset": {
                "code": "USD",
                "type": "fiat" // must be fiat
            }
        }]
    }],
    "sent": [{
        "asset_amount": {
            "amount": "0.00545",
            "asset": {
                "code": "BTC",
                "type": "crypto"
            }
        },
        "rates": [{
            "amount": "36697.25",
            "asset": {
                "code": "USD",
                "type": "fiat" 
            }
        }]
    }],
    "version": "1.0"
}

`ACH Withdraw` example:

{
	"user_id": "UUID",
	"id": "<string>",
	"datetime": "2020-06-23T15:59:21.000Z", // the datetime the transaction was confirmed
	"subtype": "ach",
	"fees": [{
		"asset_amount": {
			"amount": "2.00",
			"asset": {
				"code": "USD",
				"type": "fiat"
			}
		},
		"rates": [{
			"amount": "1.00",
			"asset": {
				"code": "USD",
				"type": "fiat"
			}
		}]
	}],
	"sent": [{
		"asset_amount": {
			"amount": "100.00",
			"asset": {
				"code": "USD",
				"type": "fiat"
			}
		},
		"rates": [{
			"amount": "1.00",
			"asset": {
				"code": "USD",
				"type": "fiat" // must be fiat
			}
		}]
	}],
	"version": "1.0"
}

Income

Transactions that classify as income can vary widely. This document will just cover a few examples but it is best to consult with TaxBit's tax specialists on what classifies as income. The model looks mostly the same for the examples with the exception of the "subtype" values.

`Interest Payment (crypto-backed loan)` Example

{  
    "user_id": "UUID",  
    "id": "<string>",  
    "datetime": "2020-07-01T00:00:00.000Z",  
    "type": "income",  
    "subtype": "interest-crypto-backed",  
    "received": [{  
        "asset_amount": {  
            "amount": "0.005",  
            "asset": {  
                "code": "BTC",  
                "type": "crypto"  
            }  
        },  
        "rates": [{  
            "amount": "1500.00",  
            "asset": {  
                "code": "USD",  
                "type": "fiat" // must be fiat  
            }  
        }]  
    }],  
    "version": "1.0"  
}

`Interest Payment (fiat-backed loan)` Example

{  
    "user_id": "UUID",  
    "id": "<string>",  
    "datetime": "2020-07-01T00:00:00.000Z",  
    "type": "income",  
    "subtype": "interest-fiat-backed",  
    "received": [{  
        "asset_amount": {  
            "amount": "10.00",  
            "asset": {  
                "code": "USD",  
                "type": "fiat"  
            }  
        },  
        "rates": [{  
            "amount": "1",  
            "asset": {  
                "code": "USD",  
                "type": "fiat" // must be fiat  
            }  
        }]  
    }],  
    "version": "1.0"  
}

`Staking Payment` Example

{  
    "user_id": "UUID",  
    "id": "<string>",  
    "datetime": "2020-07-01T00:00:00.000Z",  
    "type": "income",  
    "subtype": "staking-reward",  
    "received": [{  
        "asset_amount": {  
            "amount": "1.00",  
            "asset": {  
                "code": "XTZ",  
                "type": "crypto"  
            }  
        },  
        "rates": [{  
            "amount": "1.02",  
            "asset": {  
                "code": "USD",  
                "type": "fiat" // must be fiat  
            }  
        }],  
    }],  
    "version": "1.0"  
}

`Promotion Payment` Example

{  
    "user_id": "UUID",  
    "id": "<string>",  
    "datetime": "2020-07-01T00:00:00.000Z",  
    "type": "income",  
    "subtype": "referral-bonus",  
    "received": [{  
        "asset_amount": {  
            "amount": "0.00077",  
            "asset": {  
                "code": "BTC",  
                "type": "crypto"  
            }  
        },  
        "rates": [{  
            "amount": "6493.51",  
            "asset": {  
                "code": "USD",  
                "type": "fiat" // must be fiat  
            }  
        }]  
    }],  
    "version": "1.0"  
}

`Income Payment` Example

{  
    "user_id": "UUID",  
    "id": "<string>",  
    "datetime": "2022-07-01T00:00:00.000Z",  
    "type": "income",  
    "subtype": "payment-goods",  
    "received": [{  
        "asset_amount": {  
            "amount": "2015.61",  
            "asset": {  
                "code": "USD",  
                "type": "fiat"  
            }  
        },  
        "rates": [{  
            "amount": "6493.51",  
            "asset": {  
                "code": "USD",  
                "type": "fiat" // must be fiat  
            }  
        }]  
    }],  
    "version": "1.0"  
}

Expense

Expense transactions can vary. Please consult with TaxBit's tax specialists.

A common example is debit card transactions.

`Debit` Example

{
    "user_id": "UUID",
    "id": "<string>",
    "datetime": "2020-06-23T15:59:21.000Z",
    "type": "expense",
    "subtype": "debit",
    "sent": [{
        "asset_amount": {
            "amount": "0.00545",
            "asset": {
                "code": "BTC",
                "type": "crypto"
            }
        },
        "rates": [{
            "amount": "1834.86",
            "asset": {
                "code": "USD",
                "type": "fiat" // must be fiat
            }
        }]
    }],
    "version": "1.0",
}

Taxbit Transaction GET Response

{
    "id": "a96fbb65-47e0-40f8-97d4-dd7f61765121",
    "user_id": "b681db00-faed-4e29-bc68-265dd4bba270",
    "job_id": "eba1ebb7-85db-427d-b5e5-5b32a3d8820b",
    "external_id": "21b0b49f-3bec-537f-9b2a-7c9eeb8afd65",
    "txn_hash": null,
    "datetime": "2021-04-21T15:17:47.000Z",
    "type": "TRADE",
    "in": {
        "uuid": "3fd83fa1-1e2d-4ba2-9c01-057153d4678a",
        "asset_quantity": {
            "quantity": "1.0",
            "asset": {
                "uuid": "e2a4ad9a-92c6-11e9-a5ee-0a290192900c",
                "name": "Bitcoin",
                "code": "BTC",
                "type": "Crypto",
                "symbol": "₿"
            }
        },
        "integration": {
            "uuid": "4421ad9a-0153-4100-9939-2b636ba81a47",
            "name": "Exchange Name",
            "type": "exchange",
            "user_integration_uuid": "18f164fd-e35d-407d-94c7-b9b797282c23"
        }
    },
    "out": {
        "uuid": "a647e236-722e-49d6-b8a0-973634aec66f",
        "asset_quantity": {
            "quantity": "16.0",
            "asset": {
                "uuid": "e2a4af02-92c6-11e9-a5ee-0a290192900c",
                "name": "Ether",
                "code": "ETH",
                "type": "Crypto",
                "symbol": "Ξ"
            }
        },
        "integration": {
            "uuid": "4421ad9a-0153-4100-9939-2b636ba81a47",
            "name": "Exchange Name",
            "type": "exchange",
            "user_integration_uuid": "18f164fd-e35d-407d-94c7-b9b797282c23"
        }
    },
    "prices": [
        {
            "quantity": "35000.0",
            "asset": {
                "uuid": "e2a4afac-92c6-11e9-a5ee-0a290192900c",
                "name": "United States Dollar",
                "code": "USD",
                "type": "Fiat",
                "symbol": "$"
            }
        }
    ],
    "gain": [],
    "fees": [
        {
            "quantity": "0.01",
            "asset": {
                "uuid": "e2a4af02-92c6-11e9-a5ee-0a290192900c",
                "name": "Ether",
                "code": "ETH",
                "type": "Crypto",
                "symbol": "Ξ"
            }
        }
    ],
    "flags": null,
    "tags": [],
    "labels": [],
    "method": null,
    "memos": [],
    "hidden": null,
    "protected": null
}

Fields

id (uuid)

ID used by taxbit to identify transactions.

user_id (uuid)

User that executed the transaction.

job_id (string)

Generated internally.

external_id (string)

The transaction id supplied by the client. Used for reconciling data with the source of the data.

txn_hash (string)

The network transaction hash if applicable.

datetime (string)

Date and time of when the transaction was executed formatted: YYYY-MM-DDThh:mm:ss.sssZ.

type (enum)

enum	description
`TRADE`	The transaction does not have the user's notional currency in the `in` or `out`
`BUY`	The transaction has the user's notional currency in the `out`
`SELL`	The transaction has the user's notional currency in the `in`
`DEPOSIT`	The transaction has an `in` but no `out`
`WITHDRAW`	The transaction has an `out` but no `in`
`INCOME`	The transaction is reported as income
`EXPENSE`	The transaction is reported as an expense

in (object)

The resulting amount added to the users account.

key	description
uuid	uuid4 generated internally
asset_quantity	AssetQuantity
integration	Integration

out (object)

The resulting amount deducted from the users account.

key	description
uuid	uuid4 generated internally
asset_quantity	AssetQuantity
integration	Integration

prices (array of AssetQuantity)

The market value for the transaction. Multiple prices would be different fiat currencies for supporting different tax juristictions.

gain (array of AssetQuantity)

Realized gains for the transaction. A negative quantity indicates a loss.

fees (array of AssetQuantity)

Fees that associated with the transaction.

flags (array of strings)

Used by TaxBit to indicate possible calculation nueances for the transaction.

tags (array of key value pairs)

Reserved for future use cases.

labels (array of strings)

Reserved for future use cases.

method (string)

Indicates the ingestion method. This will be null in transactions posted to /transactions/raw.

memos (array of strings)

Notes added by TaxBit support or the user.

hidden (boolean)

if true the transaction will be hidden in the TaxBit UI and not used in tax calculations.

Metadata Object

Platform Object

📘NOTE: The platform object is only required for transactions of type 'deposit' or 'withdraw' and subtype 'blockchain'.

LineItem Object

AssetAmount Object

Asset Object

Examples

Trade

📘NOTE: Trade transactions should not have a subtype field.

Trade Example

Deposit

📘NOTE: For blockchain Deposits and Withdraw transactions, both the platform and subtype fields are required.

Blockchain Deposit Example

ACH Deposit Example

Withdraw

Blockchain Withdraw Example

ACH Withdraw example:

Income

Interest Payment (crypto-backed loan) Example

Interest Payment (fiat-backed loan) Example

Staking Payment Example

Promotion Payment Example

Income Payment Example

Expense

Debit Example

Taxbit Transaction GET Response

Fields

id (uuid)

user_id (uuid)

job_id (string)

external_id (string)

txn_hash (string)

datetime (string)

type (enum)

in (object)

out (object)

prices (array of AssetQuantity)

gain (array of AssetQuantity)

fees (array of AssetQuantity)

flags (array of strings)

tags (array of key value pairs)

labels (array of strings)

method (string)

memos (array of strings)

hidden (boolean)

protected (boolean)

📘
NOTE: The platform object is only required for transactions of type 'deposit' or 'withdraw' and subtype 'blockchain'.

📘
NOTE: Trade transactions should not have a subtype field.

`Trade` Example

📘
NOTE: For blockchain Deposits and Withdraw transactions, both the platform and subtype fields are required.

`Blockchain` Deposit Example

`ACH Deposit` Example

`Blockchain Withdraw` Example

`ACH Withdraw` example:

`Interest Payment (crypto-backed loan)` Example

`Interest Payment (fiat-backed loan)` Example

`Staking Payment` Example

`Promotion Payment` Example

`Income Payment` Example

`Debit` Example