Quickstart

This guide takes you from zero to three working calls against the Qeychain API: authenticate, load a wallet dashboard, list its holdings, and pull a tax summary. Every example is a real curl command you can copy, paste, and run.

All examples use the production base URL and the supported /api/v1 surface:

https://api.qeychain.xyz

Note

Every /api/v1/wallets/... endpoint requires authentication. A missing, invalid, or expired token returns 401 UNAUTHORIZED. See Errors & rate limits for the full error model.

Before you begin

You will need:

• A Qeychain account — an email and password with a verified email address.
• A wallet address to query. Qeychain supports EVM addresses (0x…), Bitcoin (bc1…, 1…, 3…), and Solana. Fungible tokens and native coins are tracked (no NFTs), and all values are reported in USD.

The examples below use the EVM address 0xd8da6bf26964af9d7eed9e03e53415d37aa96045. Substitute your own.

Step 1 — Authenticate

Exchange your account credentials for a bearer token by calling POST /api/v1/auth/login. The response returns a JWT access_token in its data object. Send that token in the Authorization header on every subsequent request.

curl -X POST https://api.qeychain.xyz/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "password": "your-password"}'

{
  "success": true,
  "data": {
    "id": "8a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d",
    "email": "dev@example.com",
    "full_name": "Ada Dev",
    "email_verified": true,
    "plan_name": "professional",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Save the access_token to an environment variable so the next calls can reuse it:

export QK_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Note

Access tokens are short-lived — they expire 15 minutes after issuance. When a token expires, call POST /api/v1/auth/refresh (using the refresh_token, valid for 7 days) to obtain a fresh access token. Your account’s email must be verified before login succeeds.

Step 2 — Load the wallet dashboard

GET /api/v1/wallets/{address}/dashboard returns everything you need for a first view of a wallet in a single call: current positions, portfolio totals, and an embedded tax summary.

Parameter	In	Type	Required	Description
address	path	string	Yes	Wallet address (EVM, Bitcoin, or Solana).
owned_wallets	query	string (repeatable)	No	Other addresses the same user owns, so internal transfers between them are not treated as taxable disposals.

curl https://api.qeychain.xyz/api/v1/wallets/0xd8da6bf26964af9d7eed9e03e53415d37aa96045/dashboard \
  -H "Authorization: Bearer $QK_TOKEN"

A trimmed response (several fields omitted for brevity):

{
  "success": true,
  "data": {
    "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "processing_time_ms": 3421,
    "positions": [
      {
        "symbol": "ETH",
        "name": "Ethereum",
        "chain": "ethereum",
        "quantity": "12.5",
        "current_price": "3120.44",
        "current_value": "39005.50",
        "cost_basis": "22150.00",
        "average_cost": "1772.00",
        "unrealized_gain_loss": "16855.50",
        "unrealized_gain_loss_pct": "76.10",
        "open_lots": 4,
        "partial_lots": 1,
        "is_zerion_only": false
      }
    ],
    "portfolio_value": "41230.75",
    "portfolio_cost_basis": "23980.00",
    "portfolio_unrealized_gl": "17250.75",
    "tax_summary": {
      "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "total_realized_gl": "4820.11",
      "net_short_term": "1200.00",
      "net_long_term": "3620.11",
      "wash_sale_disallowed": "0",
      "wash_sale_count": 0,
      "disposal_count": 37,
      "income_total": "512.40"
    },
    "total_lots": 63,
    "open_lots": 21,
    "closed_lots": 42,
    "transaction_count": 210,
    "ytd_realized_gl": "980.22",
    "plan_name": "professional",
    "tx_limit": 5000,
    "tx_total": null,
    "is_limited": false
  },
  "meta": {
    "request_id": "5f2b0c9e-1d7a-4a3e-9b2c-0a1b2c3d4e5f",
    "timestamp": "2026-02-19T15:04:05.123Z",
    "version": "1.0.0"
  }
}

Every successful v1 response uses this envelope: a success flag, your data payload, and a meta block with a request_id you can quote in support requests.

Tip

The first call for a wallet fetches its full on-chain history and can take several seconds; the result is cached, so repeat calls are fast. The is_limited, tx_limit, and tx_total fields tell you whether your plan tier truncated the response — see plan transaction caps.

Step 3 — List holdings

GET /api/v1/wallets/{address}/holdings returns one entry per asset-and-chain, with current value, cost basis, and unrealized gain/loss. Results are paginated.

Parameter	In	Type	Required	Description
address	path	string	Yes	Wallet address.
chain	query	string	No	Filter to a single chain (e.g. ethereum, polygon, arbitrum).
min_value	query	number	No	Hide holdings worth less than this USD amount.
sort	query	string	No	Sort order. Default value_desc. Also: value_asc, cost_desc, gain_desc, quantity_desc, symbol_asc, and their inverses.
page	query	integer	No	Page number, 1-indexed. Default 1.
per_page	query	integer	No	Items per page (max 100). Default 50.

curl "https://api.qeychain.xyz/api/v1/wallets/0xd8da6bf26964af9d7eed9e03e53415d37aa96045/holdings?sort=value_desc&per_page=50" \
  -H "Authorization: Bearer $QK_TOKEN"

{
  "success": true,
  "data": [
    {
      "symbol": "ETH",
      "name": "Ethereum",
      "chain": "ethereum",
      "contract_address": null,
      "quantity": "12.5",
      "current_price": "3120.44",
      "current_value": "39005.50",
      "cost_basis": "22150.00",
      "average_cost": "1772.00",
      "unrealized_gl": "16855.50",
      "unrealized_gl_pct": "76.10",
      "total_lots": 5,
      "open_lots": 4,
      "partial_lots": 1,
      "earliest_acquisition": "2021-05-11T08:22:41Z",
      "has_long_term_lots": true,
      "long_term_quantity": "10.0",
      "short_term_quantity": "2.5"
    }
  ],
  "meta": {
    "request_id": "7b3c1a2d-9e8f-4c0b-a1d2-3e4f5a6b7c8d",
    "timestamp": "2026-02-19T15:04:12.880Z",
    "version": "1.0.0"
  },
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 8,
    "total_pages": 1,
    "has_more": false
  },
  "partial": false,
  "still_indexing": false
}

Note

List responses carry a pagination block. Holdings responses also carry partial and still_indexing flags. For a very active wallet on a cold cache, Qeychain returns complete balances immediately with still_indexing: true while cost basis finishes computing in the background — retry the request shortly to get full cost-basis data. Details in partial and truncated results.

Step 4 — Pull a tax summary

GET /api/v1/wallets/{address}/tax-reports/summary computes realized capital gains/losses, ordinary income, and an estimated tax liability for a given tax year.

Parameter	In	Type	Required	Description
address	path	string	Yes	Wallet address.
tax_year	query	integer	Yes	Tax year to report on (2009 to the current year).
taxpayer_timezone	query	string	No	IANA timezone used to classify a disposal’s date. Default America/New_York.
short_term_rate	query	number	No	Short-term capital-gains rate for the estimate. Default 0.37.
long_term_rate	query	number	No	Long-term capital-gains rate for the estimate. Default 0.20.
ordinary_income_rate	query	number	No	Ordinary-income rate for the estimate. Default 0.37.

curl "https://api.qeychain.xyz/api/v1/wallets/0xd8da6bf26964af9d7eed9e03e53415d37aa96045/tax-reports/summary?tax_year=2024" \
  -H "Authorization: Bearer $QK_TOKEN"

{
  "success": true,
  "data": {
    "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "tax_year": 2024,
    "taxpayer_timezone": "America/New_York",
    "total_capital_gains": "4820.11",
    "net_short_term_gains": "1200.00",
    "net_long_term_gains": "3620.11",
    "total_capital_losses": "0.00",
    "wash_sale_disallowances": "0.00",
    "wash_sale_count": 0,
    "total_ordinary_income": "512.40",
    "staking_income": "512.40",
    "airdrop_income": "0.00",
    "mining_income": "0.00",
    "defi_interest_income": "0.00",
    "other_income": "0.00",
    "estimated_tax_liability": {
      "short_term_tax": "444.00",
      "long_term_tax": "724.02",
      "ordinary_income_tax": "189.59",
      "niit_tax": "184.75",
      "total_estimated_tax": "1542.36",
      "rates_used": {
        "short_term_rate": "0.37",
        "long_term_rate": "0.2",
        "ordinary_income_rate": "0.37",
        "niit_rate": "0.038"
      }
    },
    "disposal_count": 37,
    "income_event_count": 3
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "timestamp": "2026-02-19T15:04:20.401Z",
    "version": "1.0.0"
  }
}

Caution

The estimated_tax_liability block is an estimate computed from the rates you pass (or the defaults). It is informational only and is not tax advice — consult a qualified tax professional before filing. Cost basis is calculated using FIFO. Wash-sale detection is off by default (crypto is treated as property, not a security); wash_sale_disallowances and wash_sale_count stay 0 unless wash-sale tracking is explicitly enabled for your account.

Next steps

• Errors & rate limits — the standard error envelope, rate limits, plan transaction caps, and how partial or truncated results are signalled.
• Tax reporting — generate IRS Form 8949 and Schedule 1 exports (/api/v1/wallets/{address}/tax-reports/8949 and .../schedule-1).
• Holdings intelligence — portfolio summaries, per-asset detail, and lot-level cost-basis reports.
• Transactions — paginated, filterable transaction history with lineage and CSV/JSON export.