> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taxmaxi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: make your first TaxMaxi API call

> Register a TaxMaxi account, connect a wallet source, trigger a sync, and retrieve a German tax summary — all via the REST API in minutes.

This guide walks you through the full TaxMaxi workflow from a fresh account to a tax summary. You will register, log in, create a source for a wallet address, start a sync, wait for it to complete, and then calculate tax. All examples use `curl` against the production API at `https://api.taxmaxi.com`. If you prefer to connect Coinbase instead of a wallet address, skip to step 3 for the CLI alternative.

<Steps>
  <Step title="Register an account">
    Send your email, password (minimum 8 characters), and an optional display name to `POST /auth/register`. TaxMaxi will send a verification code to your email address.

    ```bash theme={null}
    curl -X POST https://api.taxmaxi.com/auth/register \
      -H "Content-Type: application/json" \
      -d '{
        "email": "you@example.com",
        "password": "your-password",
        "displayName": "Your Name"
      }'
    ```

    The response confirms the verification flow has started:

    ```json theme={null}
    {
      "email": "you@example.com",
      "redirectTo": "/verify-email"
    }
    ```
  </Step>

  <Step title="Verify your email">
    Check your inbox for the verification code, then submit it to `POST /auth/verify-email`:

    ```bash theme={null}
    curl -X POST https://api.taxmaxi.com/auth/verify-email \
      -H "Content-Type: application/json" \
      -d '{
        "code": "123456"
      }'
    ```

    A successful response returns a redirect path indicating your account is now active:

    ```json theme={null}
    {
      "redirectTo": "/home"
    }
    ```
  </Step>

  <Step title="Log in and get a session token">
    Authenticate with your email and password using the `local` provider. The response includes a `token` you will use for all subsequent requests.

    ```bash theme={null}
    curl -X POST https://api.taxmaxi.com/auth/login \
      -H "Content-Type: application/json" \
      -d '{
        "provider": "local",
        "credentials": {
          "email": "you@example.com",
          "password": "your-password"
        }
      }'
    ```

    ```json theme={null}
    {
      "token": "sess_abc123...",
      "user": {
        "id": "usr_...",
        "email": "you@example.com",
        "displayName": "Your Name"
      },
      "provider": "local",
      "expiresAt": "2026-06-14T00:00:00.000Z"
    }
    ```

    Save the `token` value — you will pass it as `Authorization: Bearer <token>` on every authenticated request.

    <Tip>
      If you prefer to connect Coinbase, use the CLI instead of steps 4–5: run `tax coinbase` after logging in. The CLI handles the OAuth flow, sync, and source creation automatically.
    </Tip>
  </Step>

  <Step title="Create a source">
    A source represents a wallet or exchange account. Create an onchain source by providing a wallet address:

    ```bash theme={null}
    curl -X POST https://api.taxmaxi.com/v1/sources \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sess_abc123..." \
      -d '{
        "type": "onchain",
        "walletAddress": "your-wallet-address"
      }'
    ```

    ```json theme={null}
    {
      "source": {
        "id": "src_...",
        "walletAddress": "your-wallet-address",
        "type": "onchain"
      },
      "created": true,
      "syncJob": null,
      "claim": null
    }
    ```

    Note the `source.id` — you will need it for the remaining steps.
  </Step>

  <Step title="Start a sync">
    Kick off transaction ingestion for your source. TaxMaxi fetches and normalizes your onchain activity in the background.

    ```bash theme={null}
    curl -X POST https://api.taxmaxi.com/v1/sources/src_.../sync \
      -H "Authorization: Bearer sess_abc123..."
    ```

    ```json theme={null}
    {
      "sourceId": "src_...",
      "jobId": "job_...",
      "status": "queued",
      "message": null
    }
    ```

    Note the `jobId` to poll for completion.
  </Step>

  <Step title="Poll for completion">
    Check the job status until `status` is `"completed"` or `"failed"`:

    ```bash theme={null}
    curl https://api.taxmaxi.com/v1/sources/src_.../jobs/job_... \
      -H "Authorization: Bearer sess_abc123..."
    ```

    ```json theme={null}
    {
      "sourceId": "src_...",
      "jobId": "job_...",
      "status": "completed",
      "importedRecords": 142,
      "normalizedRecords": 138,
      "failedRecords": 0,
      "message": null
    }
    ```

    <Note>
      Poll every few seconds. Large wallets with many transactions can take longer to sync. A `"failed"` status with a non-null `message` explains what went wrong.
    </Note>
  </Step>

  <Step title="Calculate tax">
    Once the sync is complete, request a German tax summary for the year you want:

    ```bash theme={null}
    curl -X POST https://api.taxmaxi.com/v1/sources/src_.../tax \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sess_abc123..." \
      -d '{
        "year": 2024,
        "jurisdiction": "germany"
      }'
    ```

    TaxMaxi returns a breakdown of your taxable activity for that year:

    ```json theme={null}
    {
      "year": 2024,
      "currency": "EUR",
      "taxableGains": 3200.00,
      "taxableLosses": 450.00,
      "taxFreeGains": 800.00,
      "incomeTotal": 120.00
    }
    ```

    The calculation applies FIFO capital gains rules and income classification under German tax law. `taxableGains` and `taxableLosses` reflect disposals within the taxable holding period. `taxFreeGains` covers disposals held longer than one year. `incomeTotal` covers staking and similar income events.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/authentication">
    Learn about session tokens, email verification, OAuth, and token refresh.
  </Card>

  <Card title="API reference" icon="code" href="https://api.taxmaxi.com/openapi.json">
    Browse all available endpoints in the OpenAPI specification.
  </Card>
</CardGroup>