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

# Circle Developer-Controlled Wallets — Tavryn Integration

> Learn how Tavryn provisions USDC treasury wallets on Arc Testnet via Circle Developer-Controlled Wallets — automatic setup, no Circle account required.

Tavryn uses Circle's Developer-Controlled Wallets to provision a dedicated on-chain treasury wallet for every business that connects to the platform. When Tavryn negotiates a vendor renewal and receives supervisor approval, it funds an escrow agreement and settles the payment entirely in USDC — all signed server-side through Circle's infrastructure, with no browser extension, no manual transaction approval, and no private key exposure to the AI agent.

> [!NOTE]
>
> Tavryn uses **Circle Developer-Controlled Wallets** on your behalf. You do not need a Circle account, and you do not interact with Circle's developer console directly. Your wallet is provisioned automatically when you connect your business.

## What are Developer-Controlled Wallets?

Circle Developer-Controlled Wallets are server-managed Smart Contract Account (SCA) wallets operated through Circle's API. Unlike user-controlled wallets (where the end user holds the private key), developer-controlled wallets are signed and submitted server-side by the application — in this case, by Tavryn's backend. This architecture means:

* Private keys are never held in memory on Tavryn's servers
* Private keys are never accessible to the AI negotiation agent
* All signing uses Circle's Entity Secret ciphertext encryption infrastructure
* Transactions are submitted to the Arc Testnet via Circle's transaction execution API

## Your Business Treasury Wallet

When you onboard a new business in Tavryn, the platform automatically creates a dedicated SCA wallet on **Arc Testnet** for that business. This wallet serves as the treasury from which escrow deposits and vendor settlement payments are drawn.

**1. View your wallet address**

Navigate to **Settings → Arc Treasury Settlement Wallet**. Your wallet's on-chain address (`0x...`) is displayed alongside its live USDC balance fetched directly from the Arc Testnet RPC.

**2. Fund your treasury with USDC**

Visit [faucet.circle.com](https://faucet.circle.com) to receive testnet USDC. Enter your wallet address from the Settings page and request funds. Testnet USDC typically arrives within a few seconds.

**3. Monitor your balance**

Your live treasury balance is displayed on the Executive Dashboard. Tavryn polls the Arc Testnet RPC directly using `eth_call` on the USDC precompile contract at `0x3600000000000000000000000000000000000000`, giving you ground-truth on-chain accuracy.

> [!TIP]
>
> When your treasury balance drops below **100 USDC**, Tavryn automatically sends a supervisor alert that includes a direct link to [faucet.circle.com](https://faucet.circle.com) so you can top up before the next scheduled settlement.

## SDK Initialization

Tavryn initializes the Circle Developer-Controlled Wallets SDK using your `CIRCLE_API_KEY` and `CIRCLE_ENTITY_SECRET` credentials. Both values live exclusively in your server-side environment and are never exposed to the browser or the AI agent.

```typescript theme={null}
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const circleDeveloperSdk = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
});
```

Set the following environment variables in your `.env.local` file:

```env theme={null}
CIRCLE_API_KEY=your-circle-api-key
CIRCLE_ENTITY_SECRET=your-32-byte-hex-entity-secret
CIRCLE_BLOCKCHAIN=ARC-TESTNET
```

Obtain your API key and Entity Secret from [console.circle.com](https://console.circle.com).

## Querying Your USDC Balance

Call the wallet balance API endpoint to retrieve the current USDC balance for your business treasury:

```bash theme={null}
GET /api/wallet/balance?businessId=<your-business-id>
```

**Example response:**

```json theme={null}
{
  "success": true,
  "data": {
    "address": "0xabc123...",
    "balance": 842.50,
    "isLow": false,
    "faucetUrl": "https://faucet.circle.com",
    "explorerUrl": "https://testnet.arcscan.app"
  }
}
```

The `isLow` field is `true` when the balance drops below 100 USDC, signalling that the treasury needs to be topped up before the next settlement can execute. Tavryn prefers a direct on-chain RPC read for ground-truth accuracy and falls back to the Circle API if the RPC is temporarily unavailable.

## How Tavryn Uses Your Wallet During Settlement

When the autonomous negotiation agent reaches an approved deal, it executes a sequence of on-chain operations through the Circle SDK:

**1. Create escrow agreement**

The Agent role calls `createAgreementWithSavings` on the ArcEscrow smart contract. This locks the negotiated payment amount and the protocol success fee into the escrow contract.

**2. Fund the agreement**

The Agent role calls `fundAgreement`, transferring USDC from your treasury wallet into the ArcEscrow contract's held balance.

**3. Verify vendor delivery**

Tavryn's Fulfillment Verification Engine audits the vendor's counter-signed order receipt, matching price, seats, term, and date against the agreed terms.

**4. Release payment**

Only the Verifier role — never the Agent — can call `releasePayment` to send USDC from escrow to the vendor. This role separation is enforced at the smart contract level.

> [!WARNING]
>
> Your treasury wallet must hold sufficient USDC before a settlement can execute. If the balance is insufficient at the time of an approved deal, Tavryn will pause the payment, alert your supervisors, and retry once the treasury is topped up.

## Wallet Creation Reference

For each new business, Tavryn programmatically creates a wallet set and provisions an SCA wallet on Arc Testnet:

```typescript theme={null}
// Create a wallet set
const walletSetResponse = await circleDeveloperSdk.createWalletSet({
  name: "Tavryn Treasury Wallets",
});
const walletSetId = walletSetResponse.data.walletSet.id;

// Create an SCA wallet on Arc Testnet
const createdWalletResponse = await circleDeveloperSdk.createWallets({
  accountType: "SCA",
  blockchains: ["ARC-TESTNET"],
  walletSetId,
  count: 1,
});
const [wallet] = createdWalletResponse.data.wallets;
// wallet.id      → Circle wallet UUID (used for balance queries and transfers)
// wallet.address → On-chain EVM address (used for escrow and RPC balance reads)
```

Tavryn stores the resulting wallet ID and on-chain address against your business record. All future balance queries and contract executions reference these values automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.