@thetanuts-finance/agentkit

@thetanuts-finance/agentkit

Coinbase AgentKit ActionProvider for trading Thetanuts options on Base. Lets autonomous backend agents — agents that own their own wallet — request quotations (RFQ), make encrypted sealed-bid offers, and settle, through AgentKit's TypeScript framework adapters: LangChain, Vercel AI SDK, or any MCP client via Coinbase's MCP adapter.

This package is the autonomous half of the Thetanuts agent stack: the agent's own wallet signs, unattended, under code-level safety limits. The user-in-the-loop half — where the user approves every transaction in Base Account — is the Base MCP plugin in the main SDK repo at Thetanuts-Finance/thetanuts-sdk/mcp-server/plugins/base-mcp.

When to use this vs Base MCP plugin

Need	Use
User signs every transaction in Base Account, agent prepares calldata	Base MCP plugin (SDK repo)
Agent runs unattended on a server with its own wallet (CDP, viem, Privy)	This package
Maximum reach — works in Claude Desktop, Cursor, ChatGPT, Codex	Base MCP plugin (SDK repo)
Headless trading bot, MM bot, custodied agent vault	This package
Chat client, but the agent signs by itself with its own wallet	This package as an MCP server — see Run as an MCP server

Both ultimately call the same SDK encode helpers — the difference is who signs.

New here? SETUP.md is the end-to-end guide: picking a route, CDP wallet prerequisites, safety limits, and copy-paste configs for Claude Desktop, Claude Code, Cursor, and Codex.

Walkthrough skill: SKILL.md teaches any skill-aware agent to guide you through the kit — detection, setup, funding, a read-only demo, and a safe first trade. Install it alongside the MCP server: npx skills add Thetanuts-Finance/thetanuts-agentkit -a claude-code (or -a cursor|codex, or upload to https://claude.ai/customize/skills). It also ships inside the npm package at node_modules/@thetanuts-finance/agentkit/SKILL.md.

Install

npm install @thetanuts-finance/agentkit @coinbase/agentkit \
            @thetanuts-finance/thetanuts-client

For LangChain integration:

npm install @coinbase/agentkit-langchain @langchain/langgraph @langchain/anthropic

For Vercel AI SDK:

npm install @coinbase/agentkit-vercel-ai-sdk ai @ai-sdk/anthropic

Quickstart

import { AgentKit, CdpEvmWalletProvider } from '@coinbase/agentkit';
import { getLangChainTools } from '@coinbase/agentkit-langchain';
import { thetanutsActionProvider } from '@thetanuts-finance/agentkit';

const walletProvider = await CdpEvmWalletProvider.configureWithWallet({
  apiKeyId: process.env.CDP_API_KEY_ID!,
  apiKeySecret: process.env.CDP_API_KEY_SECRET!,
  walletSecret: process.env.CDP_WALLET_SECRET!,
  networkId: 'base-mainnet',
});

const agentkit = await AgentKit.from({
  walletProvider,
  actionProviders: [
    thetanutsActionProvider({
      rpcUrl: process.env.BASE_RPC_URL,
      // REQUIRED — every write action fails closed without this.
      // See "Safety limits" below.
      safetyLimits: {
        maxNotionalUsdcPerAction: 100_000_000n, // $100 cap per action
        maxApprovalAmount: 'exact',             // never grant MAX_UINT256
        allowedCollateral: ['USDC'],            // restrict v1 to USDC
      },
    }),
  ],
});

const tools = await getLangChainTools(agentkit);
// ... wire `tools` into your LangChain ReAct agent.

See examples/langchain-quickstart.ts and examples/vercel-ai-sdk-quickstart.ts for full runnable demos.

Run as an MCP server (autonomous signing)

Coinbase ships an official MCP adapter for AgentKit — @coinbase/agentkit-model-context-protocol. Combining it with this package turns the ActionProvider into a stdio MCP server whose tools sign and broadcast on their own with the agent's CDP wallet, under the configured SafetyPolicy:

const { tools, toolHandler } = await getMcpTools(agentkit); // agentkit holds the wallet + thetanutsActionProvider
// wire into @modelcontextprotocol/sdk Server + StdioServerTransport

Full runnable server: examples/mcp-server-quickstart.ts. Step-by-step client wiring (Claude Desktop, Claude Code, Cursor, Codex) plus CDP wallet setup and safety-limit guidance: SETUP.md.

This is deliberately a different artifact from @thetanuts-finance/mcp. That server never signs — it builds calldata and the user approves every transaction in Base Account (via Base MCP). This one signs autonomously: there is no per-transaction approval click, so the SafetyPolicy caps are the only brake. Run it only with a dedicated, capped wallet. The two servers can be installed side by side — safe default plus explicit autonomous opt-in.

Actions

All actions take the AgentKit wallet provider as the first argument (injected automatically by AgentKit) and a Zod-validated arg object.

Trade actions (write)

Action	Purpose
approve	Approve an ERC20 spender (the OptionFactory). Bundled automatically by request_rfq for SELL positions; use directly only when explicit.
request_rfq	Create an RFQ for any product (PUT, CALL, spreads, butterflies, condors, iron condor). Encrypts offers automatically using the agent's stored ECDH keypair.
make_offer	Submit a sealed-bid offer on someone else's RFQ. Signs EIP-712 Offer typed-data via the wallet, encrypts the offer body, broadcasts in one tool call.
settle_rfq	Normal settlement after the offer window closes.
settle_rfq_early	Accept a specific maker's offer before the window closes. Decrypts the offer locally using the requester's ECDH key.
cancel_rfq	Cancel the agent's own RFQ.
cancel_offer	Retract an offer the agent submitted.

Read actions

Action	Purpose
get_user_positions	List the agent's (or any address's) open option positions.
get_rfq	Look up an RFQ by ID — parameters, state, hydrated offers.
get_market_prices	Oracle prices for ETH / BTC / SOL / etc.

Wallet providers

Tested against:

• CdpEvmWalletProvider — MPC-managed key, agent never sees private material. Recommended for production.
• ViemWalletProvider — Local key in a viem Account. Useful for development.
• PrivyWalletProvider — Embedded wallets, server-side.
• Any custom EvmWalletProvider subclass that implements sendTransaction, signTypedData, signMessage, getAddress, getNetwork, waitForTransactionReceipt.

The provider must report Base mainnet (chainId === 8453). The ActionProvider throws on any other network.

Architecture

The ActionProvider deliberately does NOT inject the agent's signer into the SDK. Instead it:

1. Builds a ThetanutsClient with the SDK's read provider only.
2. Uses the SDK's encode* helpers to build calldata.
3. Calls wallet.sendTransaction({ to, data }) (or wallet.signTypedData(...) for EIP-712) directly.

That way only one (well-tested) integration point — the AgentKit EvmWalletProvider — actually signs, and the SDK never needs to know about CDP / viem / Privy wallet shape.

For make_offer, the EIP-712 envelope is built via optionFactory.buildOfferTypedData(...), which verifies the live on-chain OFFER_TYPEHASH against the SDK's pinned Offer(uint256 quotationId, uint256 offerAmount, address offeror, uint64 nonce) struct definition. If the struct ever drifts due to a contract upgrade, the SDK throws rather than silently producing a bad signature.

Safety limits

Every write action runs through an in-band SafetyPolicy. The constructor's safetyLimits field is required by default — if you don't pass one, all three value-moving actions (approve, request_rfq, make_offer) throw SAFETY_LIMITS_REQUIRED and the LLM gets a safe refusal message back instead of an unbounded write.

interface SafetyLimits {
  // Hard ceiling on per-action notional in USDC base units (6 decimals).
  // 100_000_000n = $100.
  maxNotionalUsdcPerAction?: bigint;

  // Approval cap. 'exact' (default) approves the amount required and no
  // more. A bigint caps it. 'unlimited' restores v0.1.0 MAX_UINT256
  // behavior — logs a warning, NOT recommended.
  maxApprovalAmount?: 'exact' | bigint | 'unlimited';

  // Restrict RFQ creation to specific collateral tokens. Use during
  // early operation.
  allowedCollateral?: ReadonlyArray<'USDC' | 'WETH' | 'cbBTC' | ...>;

  // Per-write callback for host-side audit / per-tx confirmation / multi-sig.
  onWriteAction?: (ctx: SafetyContext) => 'allow' | 'reject';

  // Escape hatch — opt in to v0.1.0 unbounded behavior. Logs a warning.
  unsafe?: boolean;
}

Read actions (get_user_positions, get_rfq, get_market_prices) and stateless actions (settle_rfq, settle_rfq_early, cancel_rfq, cancel_offer) don't go through the policy — they can't exfiltrate funds even under prompt injection.

The get_rfq action sanitizes its response to omit encrypted offer ciphertexts and signing keys — keeping sealed-bid contents out of the LLM transcript (and out of whatever logs / training pipelines the LLM provider runs).

Other security notes

• Don't reuse the agent's CDP wallet for unrelated traffic. A dedicated wallet per agent makes incident response (revoke approvals, drain remaining balance) much simpler.
• No prompt-injection defense at the protocol layer. If your agent reads from untrusted sources (web pages, third-party messages), they may contain values for quotationId / offerorAddress / strikes chosen by an adversary. Validate provenance before calling write actions. The safety policy bounds the damage; it doesn't prevent the attempt.
• Custom wallet providers are trusted. A malicious EvmWalletProvider subclass can still sign with a different key than its getAddress() reports. The safeGetAddress helper checksum-validates the address but cannot verify the wallet actually signs with the key behind it. Pin wallet provider versions and review what you depend on.

Out of scope

• OptionBook fills (fill_order was removed in 0.2.0 — RFQ is the only write path; use the SDK's optionBook.encodeFillOrder directly if you need it).
• swap_and_fill, swap_and_call — depend on a third-party swap-quote integration (KyberSwap or 0x).
• Vault deposit/withdraw (strategyVault, wheelVault).
• Loan flows.
• Ethereum mainnet (chainId 1).

These may land in a future release.

Development

npm install
npm run typecheck
npm test          # builds, then runs the SafetyPolicy suite against dist/

The @thetanuts-finance/thetanuts-client dependency is wired to a local file:../thetanuts-sdk path in development; publishing scripts swap it to the npm-published version.

License

MIT