AgentCash SDK

TypeScript bindings for the AgentCash public API, generated from its OpenAPI document and wrapped with a small runtime for authentication, errors, React Query, custom base URLs, and custom Fetch implementations.

Core client

Use an API key from trusted server-side code:

import { AgentCash } from "@agentcash/sdk";

const agentcash = new AgentCash({
  apiKey: process.env.AGENTCASH_API_KEY!,
});

const { wallets } = await agentcash.wallets.list();
const { balance, accounts } = await agentcash.balance.get();

OAuth access tokens with the API's agentcash:read scope are also supported. A credential callback is evaluated for every request, so it can refresh or retrieve the current token lazily:

const agentcash = new AgentCash({
  accessToken: () => getAccessToken(),
});

Request OAuth tokens for the https://api.agentcash.dev/v1 resource. Browser applications should use OAuth rather than embedding a long-lived API key.

Errors and custom transport options

Non-success responses throw AgentCashError, which exposes the HTTP status and parsed response body:

import { AgentCashError } from "@agentcash/sdk";

try {
  await agentcash.wallets.list();
} catch (error) {
  if (error instanceof AgentCashError) {
    console.error(error.status, error.body);
  }
}

The constructor also accepts baseUrl and fetch for alternate environments, tests, or runtimes with a custom Fetch implementation.

React Query

React integrations live behind the @agentcash/sdk/react export so core consumers do not need React or TanStack Query. Install React Query alongside the SDK and place AgentCashProvider beneath its QueryClientProvider:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { AgentCash } from "@agentcash/sdk";
import { AgentCashProvider, useListWallets } from "@agentcash/sdk/react";
import { useMemo } from "react";

const queryClient = new QueryClient();

function Wallets() {
  const query = useListWallets();

  if (!query.data) return null;
  return <pre>{JSON.stringify(query.data.wallets, null, 2)}</pre>;
}

interface AppProps {
  getAccessToken: () => Promise<string>;
  userId: string;
}

function App({ getAccessToken, userId }: AppProps) {
  const agentcash = useMemo(
    () => new AgentCash({ accessToken: () => getAccessToken() }),
    [getAccessToken]
  );

  return (
    <QueryClientProvider client={queryClient}>
      <AgentCashProvider client={agentcash} cacheKey={userId}>
        <Wallets />
      </AgentCashProvider>
    </QueryClientProvider>
  );
}

cacheKey must be a stable identifier for the authenticated user or account. Changing it when the active account changes keeps cached API data isolated. The provider owns transport injection; there is no global SDK configuration.

Generated and handwritten code

• src/generated contains Kubb output and is committed to git.
• src/http.ts and src/client.ts provide authentication, transport, and the public core client.
• src/react provides the side-effect-free React provider and hook adapters.
• generators/provider-hook-generator.ts generates the public provider-aware hooks alongside Kubb's internal hooks.

Do not edit files under src/generated manually.

Regeneration

From the repository root, run:

pnpm api:generate

Turbo first regenerates apps/web/openapi/v1.json from the Hono API and then runs Kubb for @agentcash/sdk. Review and commit both the OpenAPI and generated SDK diffs.

Public class-client method aliases such as wallets.list() are configured in the clientMethodNames map in kubb.config.ts. Keep OpenAPI operation IDs descriptive and globally unique; React hooks and models intentionally retain names such as useListWallets and ListWalletsQueryResponse.

Validation

pnpm --filter @agentcash/sdk test
pnpm --filter @agentcash/sdk build
pnpm check