Handle transfers
Send assets moving into and out of accounts, and give deposits a cost basis so their gains can be calculated.
A transfer moves an asset into or out of an account without a sale. When an asset is deposited from outside your platform, Taxbit has no record of what it cost, so the lot it creates is missing cost basis, and a later sale from it cannot produce an accurate gain. This guide shows how to send a transfer, see the missing cost basis, and choose one of the four ways to add it.
Before you begin
- A bearer token. See Authenticate.
- An account with transactions. See Send transactions and read gains.
Send the transfer
A transfer in is a deposit, and a transfer out is a withdraw, both sent to POST /v1/transactions/external-id. Use subtype for the kind of transfer:
| Type | Subtypes |
|---|---|
deposit | ach, blockchain, card-reward, gift, cost-basis-fmv, inheritance, internal-personal |
withdraw | ach, blockchain, gift, internal-personal |
This account receives 0.75 ETH from an outside wallet:
curl -X POST $BASE_URL/v1/transactions/external-id \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "dep_40731",
"account_id": "acct_5f2e7d10",
"type": "deposit",
"subtype": "blockchain",
"datetime": "2026-09-02T09:15:00Z",
"received": [{
"asset_amount": { "amount": "0.75", "asset": { "code": "ETH", "type": "Crypto" } },
"rates": [{ "amount": "3100.00", "asset": { "code": "USD", "type": "Fiat" } }]
}]
}'You should see 201 with "status": "success".
See the missing cost basis
Read the account's ETH inventory, as in Retrieve inventory. The lot the deposit created has missing_cost_basis: true and no cost, and the summary counts it in total_quantity_missing_cost_basis. By default, every lot created from a transfer starts this way.
Give the deposit a basis
Pick the page that matches where the asset came from:
| The asset came from | Do this | Page |
|---|---|---|
| Outside your platform, and the account owner can tell you what they paid | Add user-provided lots to the deposit | Add user-provided cost basis |
| Another account of the same account owner on your platform | Link the withdrawal and the deposit | Transfer between an account owner's accounts |
| Another person, as a gift | Link to the gifter's withdrawal, or add transfer lots | Record gifts |
| An estate | Send the deposit with subtype inheritance and the value at the date of death | Record inherited assets |
Two more cases are not transfers between accounts. A deposit with subtype cost-basis-fmv records an asset acquired at its fair market value. The lot's cost is its value from rates, plus any fee, so it never starts as missing cost basis. A cost-basis-transfer with subtype wrapping or asset-name-change moves basis from one asset to another. It takes exactly one sent and one received entry, with different assets. The sent lots' total cost and acquisition dates carry to the received asset, with quantity and unit cost rescaled to the received amount. Any received quantity the sent lots don't cover is missing cost basis. A fee on this transaction is a taxable disposition. Its fields are in the Transactions reference.
Where to go next
- Add user-provided cost basis, for a deposit from outside your platform.
- API reference: Create transfer lots, Create transaction.
Updated 2 days ago
