API Reference
Start typing to search…

Transaction Data Model

The TaxBit Transaction Data Model (TDM) is the format TaxBit expects transaction data in the /transaction/ POST to be ingested into our transaction database. TDMv2 is the current version of the data model.

Field Name

Data Type

Required

Description

id

<string>

✅

ID of the Transaction. This is the ID in your (TaxBit client's) source system.

account_id

<string>

✅

ID of the Account. This is the ID in your (TaxBit client's) source system.

counterparty_transaction_id

<string>

❌

ID of the Counterparty Transaction. This is the ID in your source system. Required when type = deposit and subtype = internal-personal

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, adjustment, stake, unstake, cost-basis-transfer

This field determines the tax treatment for the transaction.

subtype

<string> enum

❌

Used to describe the transaction further than the type alone.

Specific subtypes might only be valid with specific types.

Supported sub-types by type: deposit: ach, blockchain, card-reward, gift, cost-basis-fmv, internal-personal

withdraw: ach, blockchain, gift, internal-personal

income: royalties, rent, gross-proceeds-paid-to-an-attorney, nec, payment-goods, payment-services, other, airdrop, reward, staking-reward, medical-payment, referral-bonus, interest-fiat-backed, interest-crypto-backed

expense: debit

cost-basis-transfer: wrapping, asset-name-change

dispositionMethod

<string>enum

❌

If present, this disposition method overrides the default disposition method for only this transaction.

Supported types: HIFO LIFO FIFO

fees

[LineItem]

❌

An array of the

LineItem Object

s 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.

withholdings

[LineItem]

❌

An array of the

LineItem Object

's amounts withheld by the user as part of the transaction.Note: Withholdings AmountObjects should be exclusive of fees.

version

<string>

✅

Data model version. Current version is 2.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'.

cesop

cesop

❌

Cesop Object. Contains the counterparty account id associated with the transaction.

The cesop object is required if you want to send a transaction to TaxBit for CESOP reporting purposes.

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

Cesop Object

📘

NOTE: The cesop object is only required when sending a transaction for CESOP reporting purposes.

Field NameData TypeRequiredDescription
counterparty_account_id<string>✅Identifies the counterparty of the transaction through an account ID. This Account must already exist in TaxBit's system.

LineItem Object

Field Name

Data Type

Required

Description

asset_amount

AssetAmount

✅

AssetAmount

Object

rates

tAmount`] | ✅

✅

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 NameData TypeRequiredDescription
amount<string>✅The decimal amount of the asset is a string.
assetAsset✅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 US IRS Reporting Example

{
	"account_id": "<string>",
	"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": "2.0"
}

Trade CESOP Reporting Example

{
    "user_id": "1ffbd649-bf0b-4c66-b312-dbe6dd669dc2",
    "id": "401000010-35002233-330234140-130056085644-1621054385",
    "datetime": "2023-05-15T04:53:02.000Z",
    "type": "trade",
    "version": ".0",
    "metadata": {
        "cesop": {
            "counterparty_account_id": "1ffbd649-bf0b-4c66-b312-dbe6dd669dc2"
        }
    },
    "received": [
        {
            "asset_amount": {
                "amount": "9253.805598",
                "asset": {
                    "code": "EUR",
                    "type": "fiat"
                }
            },
            "rates": [
                {
                    "amount": "1",
                    "asset": {
                        "code": "EUR",
                        "type": "fiat"
                    }
                }
            ]
        }
    ],
    "sent": [
        {
            "asset_amount": {
                "amount": "1",
                "asset": {
                    "code": "BTC",
                    "type": "crypto"
                }
            },
            "rates": [
                {
                    "amount": "9253.805598",
                    "asset": {
                        "code": "EUR",
                        "type": "fiat"
                    }
                }
            ]
        }
    ]
}

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

{
    "account_id": "<string>",
    "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": "2.0"
}

ACH Deposit Example

{
	"account_id": "<string>",
	"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": "2.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

{
    "account_id": "<string>",
    "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": "2.0"
}

ACH Withdraw example:

{
	"account_id": "<string>",
	"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": "2.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

{  
    "account_id": "<string>",  
    "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": "2.0"  
}

Interest Payment (fiat-backed loan) Example

{  
    "account_id": "<string>",  
    "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": "2.0"  
}

Staking Payment Example

{  
    "account_id": "<string>",  
    "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": "2.0"  
}

Promotion Payment Example

{  
    "account_id": "<string>",  
    "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": "2.0"  
}

Income Payment Example

{  
    "account_id": "<string>",  
    "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": "2.0"  
}

Income with Withholdings Example

{
  "user_id": "5ffbd649-bf0b-4c66-b312-dbe6dd669dc2",
  "id": "400000010-35002233-330234140-130056085644-1621054385",
  "datetime": "2021-05-15T04:53:02.000Z",
  "type": "income",
  "version": "2.0",
  "received": [
    {
      "asset_amount": {
        "amount": "9253.805598",
        "asset": {
          "code": "BTC",
          "type": "crypto"
        }
      },
      "rates": [
        {
          "amount": "0.01300975",
          "asset": {
            "code": "USD",
            "type": "fiat"
          }
        }
      ],
      "withholdings": [
        {
          "asset_amount": {
            "amount": "1",
            "asset": {
              "code": "BTC",
              "type": "crypto"
            }
          },
          "rates": [
            {
              "amount": "0.01300975",
              "asset": {
                "code": "USD",
                "type": "fiat"
              }
            }
          ],
          "regime_type": "eu-dac7"
        }
      ]
    }
  ]
}

Expense

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

A common example is debit card transactions.

Debit Example

{
    "account_id": "<string>",
    "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": "2.0",
}

Transaction GET Response

{
    "id": "a96fbb65-47e0-40f8-97d4-dd7f61765121",
    "account_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": "Ξ"
            }
        }
    ],
}

Fields

id (uuid)

The transaction ID. This is your (TaxBit client's) transaction ID.

account_id (uuid)

Account that executed the transaction. This is your (TaxBit client's) account ID.

job_id (string)

Generated internally. Job_id is returned when a transaction was provided via a file upload.

taxbit_id (string)

The TaxBit transaction ID. This is generated by TaxBit internally.

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)

enumdescription
TRADEThe transaction does not have the user's notional currency in the in or out
BUYThe transaction has the user's notional currency in the out
SELLThe transaction has the user's notional currency in the in
DEPOSITThe transaction has an in but no out
WITHDRAWThe transaction has an out but no in
INCOMEThe transaction is reported as income
EXPENSEThe transaction is reported as an expense

in (object)

The resulting amount added to the users account.

keydescription
uuiduuid4 generated internally
asset_quantityAssetQuantity
integrationIntegration

out (object)

The resulting amount deducted from the users account.

keydescription
uuiduuid4 generated internally
asset_quantityAssetQuantity
integrationIntegration

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.