read.account.pnl

Instructions

Implementation Reference

• src/tools/read/account.ts:287-341 (handler)

  The handler function for 'read.account.pnl'. Calls api.getPnlCostBasis and api.getYieldEarned, processes the raw data (filtering out large arrays like direct_deposits, flashaction_deposits/withdrawals, direct_withdrawals, yield_withdrawals, daily_yields, daily_yields_usd), and returns typed structured content with pnl_cost_basis and yield_earned.

    async ({ account_address, chain_id }) => {
      try {
        const validChainId = validateChainId(chain_id);
        const [pnlRaw, yieldRaw] = await Promise.all([
          api.getPnlCostBasis(validChainId, account_address),
          api.getYieldEarned(validChainId, account_address),
        ]);
  
        const {
          direct_deposits: _,
          flashaction_deposits,
          flashaction_withdrawals,
          direct_withdrawals,
          yield_withdrawals,
          ...pnl
        } = pnlRaw as Record<string, unknown>;
        if (Array.isArray(flashaction_deposits) && flashaction_deposits.length > 0)
          (pnl as Record<string, unknown>).flashaction_deposit_count = flashaction_deposits.length;
        if (Array.isArray(flashaction_withdrawals) && flashaction_withdrawals.length > 0)
          (pnl as Record<string, unknown>).flashaction_withdrawal_count =
            flashaction_withdrawals.length;
        if (Array.isArray(direct_withdrawals) && direct_withdrawals.length > 0)
          (pnl as Record<string, unknown>).direct_withdrawal_count = direct_withdrawals.length;
        if (Array.isArray(yield_withdrawals) && yield_withdrawals.length > 0)
          (pnl as Record<string, unknown>).yield_withdrawal_count = yield_withdrawals.length;
  
        const {
          daily_yields: _dy,
          daily_yields_usd: _dyu,
          ...yieldData
        } = yieldRaw as Record<string, unknown>;
  
        const result = { pnl_cost_basis: pnl, yield_earned: yieldData };
        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:97-100 (schema)

  Output schema (AccountPnlOutput) defined as z.object with pnl_cost_basis and yield_earned fields as z.record(z.unknown()).

  export const AccountPnlOutput = z.object({
    pnl_cost_basis: z.record(z.unknown()),
    yield_earned: z.record(z.unknown()),
  });

• src/tools/read/account.ts:269-287 (registration)

  Registration of 'read.account.pnl' tool with server.registerTool(), including annotations (title 'Get Account PnL', readOnlyHint, etc.), description, inputSchema (account_address string, chain_id number default 8453), and outputSchema reference to AccountPnlOutput.

  server.registerTool(
    "read.account.pnl",
    {
      annotations: {
        title: "Get Account PnL",
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
      description:
        "Get PnL (cost basis) and yield earned for an Arcadia account. Returns lifetime totals: cost basis vs current value (negative cost_basis = net profit withdrawn), net transfers per token, total yield earned in USD and per token. cost_basis, current_value, cost_diff are in USD (human-readable). Per-token fields (net_transfers, summed_yields_earned) are in raw token units.",
      inputSchema: {
        account_address: z.string().describe("Arcadia account address"),
        chain_id: z.number().default(8453).describe(CHAIN_ID_DESCRIPTION),
      },
      outputSchema: AccountPnlOutput,
    },
    async ({ account_address, chain_id }) => {

• src/tools/index.ts:34-40 (registration)

  registerAllTools() calls registerAccountTools(server, api, chains), which registers the 'read.account.pnl' tool along with other account read tools.

  export function registerAllTools(
    server: McpServer,
    api: ArcadiaApiClient,
    chains: Record<ChainId, ChainConfig>,
  ) {
    // Read tools
    registerAccountTools(server, api, chains);