> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cashmere.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Integration

> Integrate Cashmere cross-chain USDC transfers into AI agents using LangChain, OpenAI Assistants, crewAI, or any agent framework.

## Overview

The **Cashmere Agent SDK** (`@cashmerelabs/cashmere-agent-sdk`) turns cross-chain USDC transfers into a standard AI agent tool. Any framework that supports function calling or tool use can integrate Cashmere bridging in minutes.

**What agents can do:**

* **Simulate** a transfer to preview fees, duration, and route viability without executing
* **Execute** a transfer across 16 chains (EVM, Solana, Aptos, Sui)
* **Query** supported routes and CCTP versions programmatically

Destination minting is handled automatically by Cashmere relayers — the agent only needs to initiate the source-side burn.

***

## Install

```bash theme={null}
npm install @cashmerelabs/cashmere-agent-sdk
```

For LangChain integration, also install:

```bash theme={null}
npm install @langchain/core
```

***

## Quick Setup

```ts theme={null}
import { CashmereCCTP } from '@cashmerelabs/cashmere-agent-sdk';

const cctp = new CashmereCCTP({
  evm: { privateKey: process.env.EVM_PRIVATE_KEY },
  solana: { privateKey: process.env.SOLANA_PRIVATE_KEY },
  aptos: { privateKey: process.env.APTOS_PRIVATE_KEY },
  sui: { privateKey: process.env.SUI_PRIVATE_KEY },
});
```

Only configure the chains your agent needs. Keys are read from environment variables and used only for in-memory transaction signing.

***

## Simulate Before Execute

Use `simulate()` to let the agent preview costs before committing funds:

```ts theme={null}
const sim = await cctp.simulate({
  from: 'ethereum',
  to: 'arbitrum',
  amount: '100',
});

// {
//   supported: true,
//   version: 'v2-fast',
//   estimatedDuration: '~15 seconds',
//   estimatedFee: { cashmere: '0.12 USDC', circleBurnBps: 1.3 }
// }
```

This calls the Gas API and Circle Iris to fetch real-time fee data without submitting any transaction.

***

## Framework Integration

<Tabs>
  <Tab title="OpenAI Assistants" icon="brain">
    Import the JSON tool schemas and pass them directly to the OpenAI API:

    ```ts theme={null}
    import { bridgeToolSchema, simulateToolSchema } from '@cashmerelabs/cashmere-agent-sdk';

    const tools = [
      { type: "function", function: bridgeToolSchema },
      { type: "function", function: simulateToolSchema },
    ];

    const response = await openai.chat.completions.create({
      model: "gpt-4",
      messages: [
        { role: "system", content: "You are a cross-chain treasury agent." },
        { role: "user", content: "Bridge 500 USDC from Ethereum to Solana" },
      ],
      tools,
    });

    // When the model calls cashmere_bridge or cashmere_simulate,
    // parse the arguments and call cctp.transfer() or cctp.simulate()
    const call = response.choices[0].message.tool_calls[0];
    if (call.function.name === 'cashmere_simulate') {
      const result = await cctp.simulate(JSON.parse(call.function.arguments));
    } else if (call.function.name === 'cashmere_bridge') {
      const result = await cctp.transfer(JSON.parse(call.function.arguments));
    }
    ```

    The schema defines two tools:

    | Tool                | Description                                 |
    | ------------------- | ------------------------------------------- |
    | `cashmere_simulate` | Preview fee, duration, route — no execution |
    | `cashmere_bridge`   | Execute a cross-chain USDC transfer         |
  </Tab>

  <Tab title="LangChain" icon="link">
    The SDK provides ready-made LangChain `Tool` classes:

    ```ts theme={null}
    import { CashmereCCTP } from '@cashmerelabs/cashmere-agent-sdk';
    import {
      CashmereBridgeTool,
      CashmereSimulateTool,
    } from '@cashmerelabs/cashmere-agent-sdk/tools/langchain';

    const cctp = new CashmereCCTP({
      evm: { privateKey: process.env.EVM_PRIVATE_KEY },
    });

    const tools = [
      new CashmereBridgeTool(cctp),
      new CashmereSimulateTool(cctp),
    ];

    // Use with any LangChain agent
    import { createReactAgent } from '@langchain/langgraph/prebuilt';

    const agent = createReactAgent({ llm: chatModel, tools });
    const result = await agent.invoke({
      messages: [{ role: "user", content: "Send 200 USDC from Base to Polygon" }],
    });
    ```

    Both tools accept JSON string input and return JSON string output, compatible with all LangChain agent types.
  </Tab>

  <Tab title="crewAI" icon="users">
    crewAI uses LangChain tools natively. The same `CashmereBridgeTool` and `CashmereSimulateTool` classes work directly:

    ```python theme={null}
    # crewAI uses LangChain tools under the hood
    # In your Python crewAI setup, wrap the Node.js SDK via subprocess or HTTP

    # Or use the JSON tool schemas for a Python-native approach:
    cashmere_tool = {
        "name": "cashmere_bridge",
        "description": "Bridge USDC across chains via Cashmere CCTP...",
        "parameters": {
            "type": "object",
            "properties": {
                "from": {"type": "string", "description": "Source chain"},
                "to": {"type": "string", "description": "Destination chain"},
                "amount": {"type": "string", "description": "USDC amount"},
                "recipient": {"type": "string", "description": "Destination address"},
            },
            "required": ["from", "to", "amount", "recipient"],
        },
    }
    ```

    For TypeScript crewAI setups, use the LangChain tools directly as shown in the LangChain tab.
  </Tab>

  <Tab title="Custom Framework" icon="code">
    For any framework that supports function calling, use the raw JSON schemas:

    ```ts theme={null}
    import { bridgeToolSchema, simulateToolSchema } from '@cashmerelabs/cashmere-agent-sdk';

    // bridgeToolSchema and simulateToolSchema are plain objects:
    // {
    //   name: "cashmere_bridge",
    //   description: "...",
    //   parameters: { type: "object", properties: {...}, required: [...] }
    // }

    // Register as tools in your framework, then dispatch:
    async function handleToolCall(name: string, args: any) {
      if (name === 'cashmere_bridge') {
        return await cctp.transfer(args);
      } else if (name === 'cashmere_simulate') {
        return await cctp.simulate(args);
      }
    }
    ```
  </Tab>
</Tabs>

***

## Tool Schemas Reference

### `cashmere_bridge`

Executes a cross-chain USDC transfer.

| Parameter   | Type   | Required | Description                                              |
| ----------- | ------ | -------- | -------------------------------------------------------- |
| `from`      | string | Yes      | Source chain (e.g. `ethereum`, `arbitrum`, `solana`)     |
| `to`        | string | Yes      | Destination chain                                        |
| `amount`    | string | Yes      | USDC amount, human-readable (e.g. `"100"`)               |
| `recipient` | string | Yes      | Destination wallet address                               |
| `version`   | string | No       | `v1`, `v2-fast`, or `v2-norm` (auto-resolved if omitted) |
| `feeMode`   | string | No       | `native` or `stable` (default: `native`)                 |

**Returns:** `{ txHash, explorerUrl, version, from, to }`

### `cashmere_simulate`

Previews a transfer without executing.

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `from`    | string | Yes      | Source chain            |
| `to`      | string | Yes      | Destination chain       |
| `amount`  | string | Yes      | USDC amount             |
| `version` | string | No       | CCTP version preference |
| `feeMode` | string | No       | Fee payment mode        |

**Returns:** `{ supported, version, estimatedDuration, estimatedFee: { cashmere, circleBurnBps } }`

***

## Supported Chains

| Chain      | Domain | V1 | V2 Fast | V2 Norm |
| ---------- | ------ | -- | ------- | ------- |
| Ethereum   | 0      | Y  | Y       | Y       |
| Avalanche  | 1      | Y  | N       | Y       |
| Optimism   | 2      | Y  | Y       | Y       |
| Arbitrum   | 3      | Y  | Y       | Y       |
| Solana     | 5      | Y  | N       | Y       |
| Base       | 6      | Y  | Y       | Y       |
| Polygon    | 7      | Y  | N       | Y       |
| Sui        | 8      | Y  | N       | N       |
| Aptos      | 9      | Y  | N       | N       |
| Unichain   | 10     | Y  | Y       | Y       |
| Linea      | 11     | N  | Y       | Y       |
| Sonic      | 13     | N  | N       | Y       |
| Worldchain | 14     | N  | Y       | Y       |
| Monad      | 15     | N  | N       | Y       |
| Sei        | 16     | N  | N       | Y       |
| HyperEVM   | 19     | N  | N       | Y       |

***

## SKILL.md (Agent Context)

The SDK ships with a `SKILL.md` file that provides comprehensive context for AI agents. Load it to give your agent detailed knowledge about Cashmere CCTP:

```ts theme={null}
import { readFileSync } from 'fs';

const skillContext = readFileSync(
  require.resolve('@cashmerelabs/cashmere-agent-sdk/SKILL.md'),
  'utf-8',
);

// Pass as system message to your LLM
const messages = [
  { role: "system", content: skillContext },
  { role: "user", content: "What's the fastest way to bridge 1000 USDC to Solana?" },
];
```

The SKILL.md covers:

* All contract addresses and program IDs (public, on-chain data)
* Fee calculation formulas and gas API integration
* Per-chain transfer patterns and ABI details
* CCTP version routing rules and estimated durations

***

## Security

<Callout type="warning">
  Private keys are never logged, stored on disk, or sent to any API other than the chain's own RPC for transaction submission. The Gas API only receives domain IDs and fee parameters.
</Callout>

* Keys are provided via environment variables and used only for in-memory signing
* The SDK contains zero `console.log` statements
* All contract addresses in the SDK are public on-chain data
* The `.env.example` file ships with empty values — never commit `.env`

***

## Next Steps

* [Smart Contracts](/developers/smart-contracts) — per-chain contract details and ABI reference
* [Backend APIs](/developers/backend-apis) — Gas API and monitoring endpoints
* [Contract Addresses](/developers/contract-addresses) — deployed addresses for all 16 chains
* [GitHub](https://github.com/cashmere-prod/cashmere-agent-sdk) — source code and issues