When transactions are sent to Taxbit, digital asset inventories are computed asynchronously. Completion of inventory calculation can take anywhere from one second to several minutes. Taxbit offers multiple methods for clients to determine if the inventory surfaced via Taxbit APIs reflects the most up to date transaction data or not. Specifically, clients may use a webhook or polling strategy to fetch up-to-date inventory.

Webhook Subscription

Once a webhook subscription has been configured, Taxbit will deliver events as inventory is updated (INVENTORY_UPDATED) to the webhook subscription endpoint (see Webhooks Guide).

For example, the following POST request to buy 0.25 BTC for $20K:

POST {{base_url}}/{{base_path}}/transactions/{{external_id}}
Content-Type: application/json  
Authorization: Bearer {{auth_token}}

{  
    "account_id": "{{external_id}}",  
    "id": "1",  
    "datetime": "2024-01-01T12:13:14.123Z",  
    "type": "trade",  
    "fees": [],  
    "received": [  
        {  
            "asset_amount": {  
                "amount": "0.25",  
                "asset": {  
                    "code": "BTC",  
                    "type": "crypto"  
                }  
            },  
            "rates": [  
                {  
                    "amount": "80000.00",  
                    "asset": {  
                        "code": "USD",  
                        "type": "fiat"  
                    }  
                }  
            ]  
        }  
    ],  
    "sent": [  
        {  
            "asset_amount": {  
                "amount": "20000.00",  
                "asset": {  
                    "code": "USD",  
                    "type": "fiat"  
                }  
            },  
            "rates": [  
                {  
                    "amount": "1.00",  
                    "asset": {  
                        "code": "USD",  
                        "type": "fiat"  
                    }  
                }  
            ]  
        }  
    ],  
    "version": "2.0"  
}

Produces the following Webhook POST request delivered to your subscription endpoint:

{  
    "timestamp": "2024-08-05T19:11:47.500Z",  
    "data": [  
        {  
            "id": "2880b3a0-95e7-56c8-9511-ec8bb3c6660c",  
            "event_type": "INVENTORY_UPDATE",  
            "latest_transaction_datetime": "2024-01-01T12:13:14.123Z",  
            "account_id": "{{external_id}}",  
            "latest_transaction_id": "1"  
        }  
    ]  
}

You can then use the account_id to request the updated inventory and inventory summaries.

Polling

For customers without a webhook subscription, the /inventory and /inventory/summaries endpoints contain latest_transaction_datetime in the summary sections of each response (see below examples).

These values can be matched against the datetimes of submitted transactions to verify that inventory is up to date.

/inventory example

{
  "data": {
    "asset": {
      "uuid": "9cd9f4d4-078b-4e44-a308-7662fec0f546",
      "name": "Bitcoin",
      "code": "BTC",
      "type": "Crypto"
    },
    "fiat_asset": {
      "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
      "name": "United States Dollar",
      "code": "USD",
      "type": "Fiat"
    },
    "summary": {
      "latest_transaction_datetime": "2024-01-01T12:13:14.123Z",
      "total_quantity": "0.25",
      "total_cost": "20000",
      "average_unit_cost": "80000",
      "total_quantity_with_cost_basis": "0.25"
    },
    "lots": [
      {
        "id": "f7ab4ce6-bd4f-5c6a-a30d-55d7409b3c34",
        "acquisition_datetime": "2024-01-01T12:13:14.123Z",
        "term": "short-term",
        "quantity": "0.25",
        "fiat_asset_code": "USD",
        "cost": "20000",
        "unit_cost": "80000"
      }
    ]
  }
}

/inventory/summaries example

{
  "data": [
    {
      "asset": {
        "uuid": "9cd9f4d4-078b-4e44-a308-7662fec0f546",
        "name": "Bitcoin",
        "code": "BTC",
        "type": "Crypto"
      },
      "fiat_asset": {
        "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
        "name": "United States Dollar",
        "code": "USD",
        "type": "Fiat"
      },
      "summary": {
        "latest_transaction_datetime": "2024-01-01T12:13:14.123Z",
        "total_quantity": "0.25",
        "total_cost": "20000",
        "average_unit_cost": "80000",
        "total_quantity_with_cost_basis": "0.25"
      }
    }
  ]
}