@awakentax/sdk

Official TypeScript SDK for the Awaken Embedded Tax API. Give your users a complete crypto tax experience from your backend in one call.

npm install @awakentax/sdk

Quickstart

import { Awaken } from "@awakentax/sdk";

const awaken = new Awaken({
  clientId: process.env.AWAKEN_CLIENT_ID!,
  apiSecret: process.env.AWAKEN_API_SECRET!,
});

// Finds or creates the user, attaches their wallets, and starts importing.
const { url } = await awaken.crunch({
  userId: "user-42",
  email: "[email protected]",
  wallets: [
    { address: "0xabc…", provider: "ethereum" },
    { address: "SolanaAddress…", provider: "solana" },
  ],
});

// Send the user here. Awaken shows import progress, their tax preview,
// and lets them generate and download reports.
redirect(url);

crunch is safe to call again for the same userId: the user is reused and a fresh short-lived URL is issued each time.

What crunch returns

| Field | Meaning | | ------------- | ------------------------------------------------------------------------ | | url | Ready-to-open hosted portal URL with a short-lived access token baked in | | accessToken | The token inside url, if you want to build your own link | | expiresAt | ISO timestamp when the URL stops working | | referenceId | Echo of your userId; use it in every other call | | user | The embedded user (id, partner branding) | | accounts | Accounts created by this call |

Build your own UI

Every endpoint in the REST reference is available as a typed method. Use your userId as the referenceId.

// Gains, income, and transaction count for a tax year
const preview = await awaken.tax.preview("user-42", { year: 2025 });
preview.capGainsTotal; // "$17,090.55"

// Import progress after crunch
const { accounts } = await awaken.syncs.list("user-42");

// Reports are generated asynchronously
await awaken.reports.create("user-42", { year: 2025, reportType: "irs_8949" });
const reports = await awaken.reports.list("user-42");
const { fileName, bytes } = await awaken.reports.download(
  "user-42",
  reports[0].id,
);
// `fileName` is a single safe path segment; join it onto your own directory.

| Namespace | Methods | | ---------------------- | ------------------------------------------ | | awaken.crunch | find-or-create user + wallets + portal URL | | awaken.users | create, get | | awaken.accounts | list, create | | awaken.syncs | list, get, create | | awaken.tax | preview, recalculate, activeJob | | awaken.reports | list, create, download | | awaken.accessTokens | create | | awaken.links | create, email, forUser | | awaken.discountCodes | create |

Authentication

Pass your client id and API secret. They map to the x-client-id and x-api-secret headers. A legacy single apiKey is also accepted.

Keep credentials on your server. The only thing that should reach a browser is the url from crunch or a token from accessTokens.create, both of which are scoped to one user and expire.

The client never prints its credentials: console.log(awaken) and JSON.stringify(awaken) show nothing sensitive. Requests are sent with redirect: "manual", so a redirect is reported as an AwakenError rather than followed with your headers attached, and baseUrl must be https. A local sandbox over plain http needs allowInsecureBaseUrl: true; never set that in production.

Errors

Non-2xx responses, redirects, and 2xx bodies that are not the JSON envelope throw an AwakenError carrying the API's message, the HTTP status, and the raw body. error.body and error.path can include the reference id and, on validation errors, the submitted email, so redact them before sending errors to a log aggregator.

import { AwakenError } from "@awakentax/sdk";

try {
  await awaken.tax.preview("missing-user");
} catch (error) {
  if (error instanceof AwakenError && error.status === 404) {
    // create the user first
  }
}

Options

new Awaken({
  clientId,
  apiSecret,
  baseUrl: "https://api.awaken.tax/api", // default; must be https
  allowInsecureBaseUrl: false, // default; only for a plain-http local sandbox
  portalUrl: "https://embed.awaken.tax", // default, used when building portal URLs
  timeoutMs: 30_000, // default
  fetch: customFetch, // default: global fetch (Node 18+)
});

Requirements

Node 18 or newer, or any runtime with a global fetch. Ships ESM and CommonJS builds with type declarations.