# SDK

`@divigent/sdk` is a TypeScript SDK for putting idle USDC to work while keeping agent wallets liquid for x402 requests.

The SDK is viem-native and works with a viem wallet client. The standard path is an EOA wallet client; smart-account integrations can use the SDK when they provide compatible viem signing and transaction-sending behavior.

{% hint style="warning" %}
Base mainnet uses real Circle USDC and broadcasts real transactions. Start with small caps, verify the configured addresses, and test on Base fork before moving meaningful funds.
{% endhint %}

{% stepper %}
{% step %}

### Install

```bash
npm install @divigent/sdk viem @x402/core @x402/fetch
```

Requires Node.js 20.10 or newer.
{% endstep %}

{% step %}

### Create A Client

Base mainnet:

```ts
import { Divigent, evmAddress, formatUsdc } from '@divigent/sdk';
import { createPublicClient, createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const rpcUrl = process.env.BASE_MAINNET_RPC_URL!;

const publicClient = createPublicClient({
  chain: base,
  transport: http(rpcUrl),
});

const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(rpcUrl),
});

const divigent = Divigent.create({
  publicClient,
  walletClient,
  chain: 'base',
});

await divigent.verifyAddresses();

const wallet = evmAddress(account.address);
const position = await divigent.getPosition(wallet);

console.log(`current value: ${formatUsdc(position.currentValue)} USDC`);
```

For Base Sepolia, use `baseSepolia`, `BASE_SEPOLIA_RPC_URL`, and `chain: 'base-sepolia'`.
{% endstep %}

{% step %}

### Initialize The Wallet

Initialize the wallet once before deposits, withdrawals, or x402 automation.

```ts
const initTx = await divigent.ensureInitializedAndWait({ wallet });

if (initTx !== undefined) {
  console.log(`initialized wallet: ${initTx}`);
}
```

`ensureInitializedAndWait(...)` returns `undefined` when the wallet is already initialized.
{% endstep %}

{% step %}

### Deposit USDC

Use `depositWithPermitAndWait` for the simplest deposit path. Base mainnet Circle USDC supports the permit fields used by the SDK. If permit is unavailable for a supported signer-wallet path, the SDK can fall back to `approveUsdc + deposit`.

```ts
import { formatUsdc, parseUsdc } from '@divigent/sdk';

const amount = parseUsdc('10');

const deposit = await divigent.depositWithPermitAndWait({
  amount,
  wallet,
  fallbackOnPermitUnsupported: true,
});

console.log(`deposit tx: ${deposit.txHash}`);
console.log(`minted: ${formatUsdc(deposit.sharesMinted)} dvUSDC`);
```

You can also approve and deposit explicitly:

```ts
const amount = parseUsdc('10');

await divigent.approveUsdc(amount);
const deposit = await divigent.depositAndWait({ amount, wallet });

console.log(`deposit tx: ${deposit.txHash}`);
```

{% endstep %}

{% step %}

### Withdraw USDC

To withdraw a target net amount, preview how many dvUSDC shares are needed and then withdraw with a slippage guard.

```ts
import { formatUsdc, parseUsdc } from '@divigent/sdk';

const desired = parseUsdc('2.5');
const shares = await divigent.previewWithdrawNet(desired, wallet);

const withdrawal = await divigent.withdrawAndWait({
  shares,
  wallet,
  slippageBps: 50,
});

console.log(`withdraw tx: ${withdrawal.txHash}`);
console.log(`received: ${formatUsdc(withdrawal.usdcReturned)} USDC`);
```

{% hint style="info" %}
Base mainnet uses Circle USDC at `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`. Base Sepolia uses Divigent's configured test USDC. Use `divigent.addresses.usdc` when configuring x402 payment assets.
{% endhint %}
{% endstep %}
{% endstepper %}

## Supported Chains

| Chain        | SDK chain id   | USDC                          |
| ------------ | -------------- | ----------------------------- |
| Base mainnet | `base`         | Circle USDC                   |
| Base Sepolia | `base-sepolia` | Divigent configured test USDC |

## Next Steps

* [x402 Quickstart](/divigent-docs/quick-start/x402-with-sdk.md) to add automatic withdrawal and redeposit around agent payments.
* [SDK Integration](/divigent-docs/integration/sdk-integration.md) for the full buyer/seller x402 integration pattern.
* [SDK Reference](/divigent-docs/sdk/api-reference.md) for the full function surface.
* [Architecture Overview](/divigent-docs/architecture/overview.md) for how the contracts work under the SDK.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://divigent.gitbook.io/divigent-docs/quick-start/sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.