feat: add spot history command

Adds swap trade history to the spot module using the Datapi
`_datapi/v1/txs/users` endpoint. Groups double-bookkeeping API entries
by txHash into input/output pairs, resolves token metadata via batch
search, and supports filtering by token, date range, and pagination.

Author: AaronCQL

docs/spot.md

@@ -102,6 +102,41 @@ jup spot portfolio --address <wallet-address>
 }
 ```
 
+### View trade history
+
+```bash
+jup spot history --address <wallet-address>
+jup spot history --key mykey
+jup spot history --address <wallet-address> --token SOL
+jup spot history --address <wallet-address> --after 2025-01-01 --before 2025-02-01
+jup spot history --address <wallet-address> --limit 10 --offset 123
+```
+
+- With no `--address` or `--key`, uses the active key's wallet
+- `--token` filters by token (symbol or mint address)
+- `--after` / `--before` accept ISO 8601 dates or UNIX timestamps
+- `--limit` defaults to 10, max 15
+- `--offset` is used for pagination; use the `next` value from the previous response to fetch the next page of results
+
+```js
+// Example JSON response:
+{
+  "trades": [
+    {
+      "time": "2025-01-15T10:30:00.000Z", // ISO 8601 timestamp
+      "inputToken": { "id": "So11...1112", "symbol": "SOL", "decimals": 9 },
+      "outputToken": { "id": "EPjF...USDC", "symbol": "USDC", "decimals": 6 },
+      "inAmount": "1", // human-readable decimal amount
+      "outAmount": "84.994059", // human-readable decimal amount
+      "inUsdValue": 84.98, // USD value
+      "outUsdValue": 84.99,
+      "signature": "3dV98zG..." // tx signature
+    }
+  ],
+  "next": "123" // pagination offset for next page of results; use with --offset to fetch next page
+}
+```
+
 ### Transfer tokens
 
 ```bash

src/clients/DatapiClient.ts

@@ -95,16 +95,63 @@ type GetSearchTokensRequest = {
 
 type GetSearchTokensResponse = Token[];
 
+export type SpotTrade = {
+  type: "buy" | "sell";
+  usdVolume: number;
+  profit: number;
+  cost: number;
+  txHash: string;
+  assetId: string;
+  blockTime: string;
+  amount: number;
+  price: number;
+};
+
+type GetSpotHistoryResponse = {
+  userTrades: SpotTrade[];
+  next: string | null;
+};
+
 export class DatapiClient {
   static readonly #ky = ky.create({
-    prefixUrl: `${ClientConfig.host}/tokens/v2`,
+    prefixUrl: ClientConfig.host,
     headers: ClientConfig.headers,
     throwHttpErrors: false,
   });
 
-  public static async search(
+  public static async getTokensSearch(
     req: GetSearchTokensRequest
   ): Promise<GetSearchTokensResponse> {
-    return this.#ky.get("search", { searchParams: req }).json();
+    return this.#ky.get("tokens/v2/search", { searchParams: req }).json();
+  }
+
+  public static async getSwapsByAddress(params: {
+    address: string;
+    assetId?: string;
+    after?: string;
+    before?: string;
+    limit?: number;
+    offset?: string;
+  }): Promise<GetSpotHistoryResponse> {
+    const searchParams: Record<string, string | number> = {
+      addresses: params.address,
+      includeCapitalSide: "true",
+    };
+    if (params.assetId) {
+      searchParams.assetId = params.assetId;
+    }
+    if (params.after) {
+      searchParams.fromTs = params.after;
+    }
+    if (params.before) {
+      searchParams.toTs = params.before;
+    }
+    if (params.limit) {
+      searchParams.limit = Math.min(params.limit, 30);
+    }
+    if (params.offset) {
+      searchParams.offset = params.offset;
+    }
+    return this.#ky.get("_datapi/v1/txs/users", { searchParams }).json();
   }
 }

src/clients/UltraClient.ts

@@ -88,8 +88,8 @@ type GetTransferTxResponse =
       requestId: string;
       transaction: string; // base64 encoded wire tx
       expireAt: string;
-      feeAmount: number;
-      feeUsdAmount: number;
+      feeAmount?: number | undefined;
+      feeUsdAmount?: number | undefined;
     }
   | {
       error: string;

src/commands/SpotCommand.ts

@@ -1,8 +1,13 @@
 import { findAssociatedTokenPda } from "@solana-program/token";
 import type { Address, Base64EncodedBytes } from "@solana/kit";
+import chalk from "chalk";
 import type { Command } from "commander";
 
-import { DatapiClient, type Token } from "../clients/DatapiClient.ts";
+import {
+  DatapiClient,
+  type SpotTrade,
+  type Token,
+} from "../clients/DatapiClient.ts";
 import {
   UltraClient,
   type HoldingsTokenAccount,
@@ -56,6 +61,20 @@ export class SpotCommand {
       .option("--address <address>", "Wallet address to look up")
       .option("--key <name>", "Key to use (overrides active key)")
       .action((opts) => this.portfolio(opts));
+    spot
+      .command("history")
+      .description("View swap trade history for a wallet")
+      .option("--key <name>", "Key to use (overrides active key)")
+      .option("--address <address>", "Wallet address to look up")
+      .option("--token <token>", "Filter by token (symbol or mint address)")
+      .option("--after <date>", "Show trades after this date or UNIX timestamp")
+      .option(
+        "--before <date>",
+        "Show trades before this date or UNIX timestamp"
+      )
+      .option("--limit <n>", "Max number of results (max: 15)", "10")
+      .option("--offset <offset>", "Pagination offset for next page of results")
+      .action((opts) => this.history(opts));
     spot
       .command("transfer")
       .description("Transfer tokens to another wallet")
@@ -81,7 +100,7 @@ export class SpotCommand {
       throw new Error("--limit must be a number");
     }
 
-    const tokens = await DatapiClient.search({
+    const tokens = await DatapiClient.getTokensSearch({
       query: opts.search,
       limit: opts.limit,
     });
@@ -361,7 +380,7 @@ export class SpotCommand {
     }
     const resolved = await Promise.all(
       batches.map((batch) =>
-        DatapiClient.search({
+        DatapiClient.getTokensSearch({
           query: batch.join(","),
           limit: BATCH_SIZE.toString(),
         })
@@ -551,7 +570,7 @@ export class SpotCommand {
     }
 
     const networkFee = NumberConverter.fromChainAmount(
-      txResponse.feeAmount.toString(),
+      txResponse.feeAmount?.toString() ?? 0n,
       Asset.SOL.decimals
     );
 
@@ -573,6 +592,142 @@ export class SpotCommand {
     });
   }
 
+  private static async history(opts: {
+    key?: string;
+    address?: string;
+    token?: string;
+    after?: string;
+    before?: string;
+    limit: string;
+    offset?: string;
+  }): Promise<void> {
+    if (opts.address && opts.key) {
+      throw new Error("Only one of --address or --key can be provided.");
+    }
+
+    const limit = Number(opts.limit);
+    if (isNaN(limit) || limit <= 0) {
+      throw new Error("--limit must be a positive number.");
+    }
+
+    const address =
+      opts.address ??
+      (await Signer.load(opts.key ?? Config.load().activeKey)).address;
+    const targetAsset = opts.token
+      ? await this.resolveToken(opts.token)
+      : undefined;
+    const { userTrades, next } = await DatapiClient.getSwapsByAddress({
+      address,
+      assetId: targetAsset?.id,
+      after: opts.after ? this.parseTimestamp(opts.after) : undefined,
+      before: opts.before ? this.parseTimestamp(opts.before) : undefined,
+      limit: opts.limit ? limit * 2 : undefined, // double bookkeeping
+      offset: opts.offset,
+    });
+
+    // Group double-bookkeeping entries by txHash
+    const grouped = new Map<string, SpotTrade[]>();
+    for (const t of userTrades) {
+      const existing = grouped.get(t.txHash);
+      if (existing) {
+        existing.push(t);
+      } else {
+        grouped.set(t.txHash, [t]);
+      }
+    }
+
+    // Resolve token metadata for all unique mints
+    const mints = [...new Set(userTrades.map((t) => t.assetId))];
+    const tokenMap = new Map<string, Token>();
+    if (mints.length > 0) {
+      const tokens = await DatapiClient.getTokensSearch({
+        query: mints.join(","),
+        limit: mints.length.toString(),
+      });
+      for (const token of tokens) {
+        tokenMap.set(token.id, token);
+      }
+    }
+
+    const trades = [...grouped.values()]
+      .map((entries) => {
+        const sell = entries.find((e) => e.type === "sell");
+        const buy = entries.find((e) => e.type === "buy");
+        const inputInfo = sell ? tokenMap.get(sell.assetId) : undefined;
+        const outputInfo = buy ? tokenMap.get(buy.assetId) : undefined;
+        return {
+          time: (sell ?? buy)!.blockTime,
+          inputToken: inputInfo
+            ? {
+                id: inputInfo.id,
+                symbol: inputInfo.symbol,
+                decimals: inputInfo.decimals,
+              }
+            : null,
+          outputToken: outputInfo
+            ? {
+                id: outputInfo.id,
+                symbol: outputInfo.symbol,
+                decimals: outputInfo.decimals,
+              }
+            : null,
+          inAmount: sell ? String(sell.amount) : null,
+          outAmount: buy ? String(buy.amount) : null,
+          inUsdValue: sell ? sell.usdVolume : null,
+          outUsdValue: buy ? buy.usdVolume : null,
+          signature: (sell ?? buy)!.txHash,
+        };
+      })
+      .slice(0, limit);
+
+    if (Output.isJson()) {
+      Output.json({
+        trades,
+        next,
+      });
+      return;
+    }
+
+    if (trades.length === 0) {
+      throw new Error("No trades found.");
+    }
+
+    Output.table({
+      type: "horizontal",
+      headers: {
+        time: "Time",
+        input: "Input",
+        output: "Output",
+        signature: "Tx Signature",
+      },
+      rows: trades.map((t) => ({
+        time: new Date(t.time).toLocaleString(),
+        input: t.inAmount
+          ? `${t.inAmount} ${t.inputToken?.symbol ?? "?"} (${Output.formatDollar(t.inUsdValue ?? undefined)})`
+          : chalk.gray("\u2014"),
+        output: t.outAmount
+          ? `${t.outAmount} ${t.outputToken?.symbol ?? "?"} (${Output.formatDollar(t.outUsdValue ?? undefined)})`
+          : chalk.gray("\u2014"),
+        signature: t.signature,
+      })),
+    });
+
+    if (next) {
+      console.log("\nNext offset:", next);
+    }
+  }
+
+  private static parseTimestamp(value: string): string {
+    if (/^\d+$/.test(value)) {
+      return new Date(Number(value) * 1000).toISOString();
+    }
+    const ms = new Date(value).getTime();
+    if (isNaN(ms)) {
+      throw new Error(`Invalid date: ${value}`);
+    }
+    return new Date(ms).toISOString();
+  }
+
   private static validateAmountOpts(opts: {
     amount?: string;
     rawAmount?: string;
@@ -597,7 +752,10 @@ export class SpotCommand {
   }
 
   private static async resolveToken(input: string): Promise<Token> {
-    const [token] = await DatapiClient.search({ query: input, limit: "1" });
+    const [token] = await DatapiClient.getTokensSearch({
+      query: input,
+      limit: "1",
+    });
     if (!token) {
       throw new Error(`Token not found: ${input}`);
     }