read.account.history

Instructions

Implementation Reference

• src/tools/read/account.ts:221-267 (registration)

  Registration of the 'read.account.history' tool with MCP server, including annotations, description, inputSchema, outputSchema, and the handler callback

  server.registerTool(
    "read.account.history",
    {
      annotations: {
        title: "Get Account History",
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
      description:
        "Get historical collateral and debt values for an Arcadia account over time. Returns a time series of snapshots (timestamp, collateral_value, debt_value, net_value). Each value is the account's net value in USD (human-readable, not raw units). Useful for charting account performance over a period.",
      inputSchema: {
        account_address: z.string().describe("Arcadia account address"),
        days: z.number().default(14).describe("Number of days of history (default 14)"),
        chain_id: z.number().default(8453).describe(CHAIN_ID_DESCRIPTION),
      },
      outputSchema: AccountHistoryOutput,
    },
    async ({ account_address, days, chain_id }) => {
      try {
        const validChainId = validateChainId(chain_id);
        if (days <= 0) {
          return {
            content: [{ type: "text" as const, text: "Error: days must be a positive number" }],
            isError: true,
          };
        }
        const raw = await api.getAccountHistory(validChainId, account_address, days);
        const result = { history: Array.isArray(raw) ? raw : [] };
        return {
          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
          structuredContent: result,
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/tools/read/account.ts:240-267 (handler)

  Handler function for read.account.history: validates chainId, checks days > 0, calls api.getAccountHistory(), and returns the result as { history: [...] }

    async ({ account_address, days, chain_id }) => {
      try {
        const validChainId = validateChainId(chain_id);
        if (days <= 0) {
          return {
            content: [{ type: "text" as const, text: "Error: days must be a positive number" }],
            isError: true,
          };
        }
        const raw = await api.getAccountHistory(validChainId, account_address, days);
        const result = { history: Array.isArray(raw) ? raw : [] };
        return {
          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
          structuredContent: result,
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/tools/output-schemas.ts:93-95 (schema)

  Output schema (AccountHistoryOutput) defining that the response contains an array of history records

  export const AccountHistoryOutput = z.object({
    history: z.array(z.record(z.unknown())),
  });

• src/clients/api.ts:99-108 (helper)

  API client method getAccountHistory() that calls the external API endpoint /accounts/historic_account_values with chain_id, account_address, start, and end timestamps

  async getAccountHistory(chainId: number, account: string, days = 14) {
    const end = Math.floor(Date.now() / 1000);
    const start = end - days * 86400;
    return this.get("/accounts/historic_account_values", {
      chain_id: chainId,
      account_address: account,
      start,
      end,
    });
  }