Custom Integration

Build your own tax UI around three core API calls: create the user, read the preview, and generate a report.

1. Create the user and wallets

Send your stable user ID and their wallet addresses to POST /api/crunch. Awaken creates or reuses the embedded user, adds supported wallets, and starts the import and calculation work.

bash

curl https://api.awaken.tax/api/crunch \
  -H "content-type: application/json" \
  -H "x-api-key: $AWAKEN_PARTNER_KEY" \
  --data '{"userId":"user-42","email":"user@example.com","wallets":[{"address":"0xabc…","provider":"ethereum"},{"address":"SolanaAddress…","provider":"solana"}]}'

2. Read the tax preview

Use the same user ID as the referenceId. The preview returns current processing state plus transaction count, capital gains, income, futures, and year-specific totals for your UI.

bash

curl "https://api.awaken.tax/api/users/user-42/preview?year=2025" \
  -H "x-api-key: $AWAKEN_PARTNER_KEY"

3. Generate a tax report

When the user's data is ready, request the report type and tax year your UI offers. Report generation is asynchronous.

That is the core integration

Create, preview, and report are enough for the first version of a custom embedded tax experience.

bash

curl https://api.awaken.tax/api/users/user-42/reports \
  -H "content-type: application/json" \
  -H "x-api-key: $AWAKEN_PARTNER_KEY" \
  --data '{"year":2025,"reportType":"summary_report","email":"user@example.com"}'

Poll and download the result

List GET /api/users/:referenceId/reports until the requested report is ready, then use the report download endpoint. Keep polling conservative and stop on completed or failed states.

bash

curl "https://api.awaken.tax/api/users/user-42/reports" \
  -H "x-api-key: $AWAKEN_PARTNER_KEY"

Use your own stable user ID

The userId you send at creation becomes the referenceId in later paths. Store it with returned report IDs and use it consistently instead of identifying users by email.

Jobs are asynchronous

The preview may show importing or recalculating before final totals are available. Display that state and retry with backoff.