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

# Using the API

This guide documents every argument involved in deploying a DeFindex vault — whether you call the factory smart contract directly or use the DeFindex REST API. Read the [Vault Creation Requirements](/integration-guide/creating-a-defindex-vault/index#vault-creation-requirements) section first before proceeding.

***

## Quick Reference: Contract Addresses

### Testnet

Stellar wipes the testnet periodically, and these addresses stop working when it does. The next scheduled reset is December 16, 2026. If an address no longer works, let us know via Discord so we can update the docs.

| Contract             | Address                                                    |
| -------------------- | ---------------------------------------------------------- |
| Factory              | `CDSCWE4GLNBYYTES2OCYDFQA2LLY4RBIAX6ZI32VSUXD7GO6HRPO4A32` |
| Soroswap Router      | `CCJUD55AG6W5HAI5LRVNKAE5WDP5XGZBUDS5WNTIVDU7O264UZZE7BRD` |
| XLM (native SAC)     | `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC` |
| BlendUSDC            | `CAQCFVLOBK5GIULPNZRGATJJMIZL5BSP7X5YJVMGCPTUEPFM4AVSRCJU` |
| CETES token          | `CC72F57YTPX76HAA64JQOEGHQAPSADQWSY5DWVBR66JINPFDLNCQYHIC` |
| USDC Blend Strategy  | `CALLOM5I7XLQPPOPQMYAHUWW4N7O3JKT42KQ4ASEEVBXDJQNJOALFSUY` |
| XLM Blend Strategy   | `CDVLOSPJPQOTB6ZCWO5VSGTOLGMKTXSFWYTUP572GTPNOWX4F76X3HPM` |
| CETES Blend Strategy | `CCP4RBDWPRNO2LWO23XFU4BBLGA73J5N3BK7EHRJUHVN33YEMMFB2MBE` |

### Mainnet

| Contract                 | Address                                                    |
| ------------------------ | ---------------------------------------------------------- |
| Factory                  | `CDKFHFJIET3A73A2YN4KV7NSV32S6YGQMUFH3DNJXLBWL4SKEGVRNFKI` |
| Soroswap Router          | `CAG5LRYQ5JVEUI5TEID72EYOVX44TTUJT5BQR2J6J77FH65PCCFAJDDH` |
| XLM (native SAC)         | `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC` |
| USDC (Circle)            | `CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75` |
| USDC Fixed Pool Strategy | `CDB2WMKQQNVZMEBY7Q7GZ5C7E7IAFSNMZ7GGVD6WKTCEWK7XOIAVZSAP` |
| EURC Fixed Pool Strategy | `CC5CE6MWISDXT3MLNQ7R3FVILFVFEIH3COWGH45GJKL6BD2ZHF7F7JVI` |
| XLM Fixed Pool Strategy  | `CDPWNUW7UMCSVO36VAJSQHQECISPJLCVPDASKHRC5SEROAAZDUQ5DG2Z` |

For the complete list of mainnet strategies, see [Contract Deployments](/contract-deployments/index).

***

## `POST /factory/create-vault`

Builds an unsigned XDR to deploy a vault. You must sign the XDR and submit it via `POST /send`.

```http theme={null}
POST https://api.defindex.io/factory/create-vault?network=testnet
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

### Request Body

```json theme={null}
{
  "roles": {
    "manager": "GACKTN5D...",
    "emergencyManager": "GACKTN5D...",
    "rebalanceManager": "GACKTN5D...",
    "feeReceiver": "GACKTN5D..."
  },
  "vaultFeeBps": 100,
  "assets": [
    {
      "address": "CAQCFVLOBK5GIULPNZRGATJJMIZL5BSP7X5YJVMGCPTUEPFM4AVSRCJU",
      "strategies": [
        {
          "address": "CALLOM5I7XLQPPOPQMYAHUWW4N7O3JKT42KQ4ASEEVBXDJQNJOALFSUY",
          "name": "BlendUSDC Strategy",
          "paused": false
        }
      ]
    }
  ],
  "name": "My USDC Vault",
  "symbol": "MUSDC",
  "upgradable": true,
  "caller": "GACKTN5D..."
}
```

### Field Reference

| Field                           | Type         | Required | Description                                               |
| ------------------------------- | ------------ | -------- | --------------------------------------------------------- |
| `roles.manager`                 | `string`     | Yes      | Stellar address for the Manager role                      |
| `roles.emergencyManager`        | `string`     | Yes      | Stellar address for the Emergency Manager role            |
| `roles.rebalanceManager`        | `string`     | Yes      | Stellar address for the Rebalance Manager role            |
| `roles.feeReceiver`             | `string`     | Yes      | Stellar address for the Fee Receiver role                 |
| `vaultFeeBps`                   | `number`     | Yes      | Vault fee in basis points (0–9000). `100` = 1%            |
| `assets`                        | `Asset[]`    | Yes      | Array of assets the vault will manage                     |
| `assets[].address`              | `string`     | Yes      | Token contract address for this asset                     |
| `assets[].strategies`           | `Strategy[]` | Yes      | Strategies that manage this asset                         |
| `assets[].strategies[].address` | `string`     | Yes      | Strategy contract address                                 |
| `assets[].strategies[].name`    | `string`     | Yes      | Human-readable name stored on-chain                       |
| `assets[].strategies[].paused`  | `boolean`    | Yes      | Whether the strategy starts paused. Use `false`           |
| `name`                          | `string`     | Yes      | Vault display name (stored on-chain)                      |
| `symbol`                        | `string`     | Yes      | Vault token symbol for dfTokens (e.g., `MUSDC`)           |
| `upgradable`                    | `boolean`    | Yes      | Whether the vault contract can be upgraded by the Manager |
| `caller`                        | `string`     | Yes      | Stellar address of the deployer (signs the transaction)   |

### Response

```json theme={null}
{
  "xdr": "AAAAAgAAAAB...",
  "simulationResponse": { ... },
  "error": null
}
```

Sign the returned `xdr` with the `caller`'s key and submit via `POST /send?network=testnet`.

***

## `POST /factory/create-vault-deposit`

Creates a vault **and** performs the initial deposit atomically. This is the recommended approach since it handles Steps 3 and 4 in a single transaction.

```http theme={null}
POST https://api.defindex.io/factory/create-vault-deposit?network=testnet
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

### Request Body

```json theme={null}
{
  "roles": {
    "manager": "GACKTN5D...",
    "emergencyManager": "GACKTN5D...",
    "rebalanceManager": "GACKTN5D...",
    "feeReceiver": "GACKTN5D..."
  },
  "vaultFeeBps": 100,
  "assets": [
    {
      "address": "CAQCFVLOBK5GIULPNZRGATJJMIZL5BSP7X5YJVMGCPTUEPFM4AVSRCJU",
      "strategies": [
        {
          "address": "CALLOM5I7XLQPPOPQMYAHUWW4N7O3JKT42KQ4ASEEVBXDJQNJOALFSUY",
          "name": "BlendUSDC Strategy",
          "paused": false
        }
      ]
    }
  ],
  "name": "My USDC Vault",
  "symbol": "MUSDC",
  "upgradable": true,
  "caller": "GACKTN5D...",
  "depositAmounts": [10000000]
}
```

### Additional Field

| Field            | Type       | Required | Description                                                                                                    |
| ---------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `depositAmounts` | `number[]` | Yes      | Initial deposit amounts in **stroops**, one per asset in the same order as `assets`. Must be ≥ 1001 per asset. |

All other fields are identical to `create-vault` above.

> **Decimal reference:** 1 USDC = `10_000_000` stroops (7 decimals). 1 XLM = `10_000_000` stroops. The minimum `1001` stroops equals **0.0001001 units**.

### Response

Same shape as `create-vault`:

```json theme={null}
{
  "xdr": "AAAAAgAAAAB...",
  "simulationResponse": { ... },
  "error": null
}
```

***

## `POST /factory/create-vault-auto-invest`

Creates a vault, makes the initial deposit, **and** immediately rebalances (invests) into strategies — all in one batched transaction. At the end it also transfers the Manager role to the final address. This is the most convenient option for fully automated deployments.

```http theme={null}
POST https://api.defindex.io/factory/create-vault-auto-invest?network=testnet
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

### Request Body

```json theme={null}
{
  "caller": "GBZXUKUY...",
  "roles": {
    "manager": "GBAJGSZQ...",
    "emergencyManager": "GBAJGSZQ...",
    "rebalanceManager": "GBAJGSZQ...",
    "feeReceiver": "GBAJGSZQ..."
  },
  "name": "Auto-Invest USDC Vault",
  "symbol": "AIUSDC",
  "vaultFee": 100,
  "upgradable": true,
  "assets": [
    {
      "address": "CAQCFVLOBK5GIULPNZRGATJJMIZL5BSP7X5YJVMGCPTUEPFM4AVSRCJU",
      "symbol": "USDC",
      "amount": 10000000,
      "strategies": [
        {
          "address": "CALLOM5I7XLQPPOPQMYAHUWW4N7O3JKT42KQ4ASEEVBXDJQNJOALFSUY",
          "name": "BlendUSDC Strategy",
          "amount": 10000000
        }
      ]
    }
  ]
}
```

### Field Reference

| Field                           | Type         | Required | Description                                                                                                                         |
| ------------------------------- | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `caller`                        | `string`     | Yes      | Deployer's Stellar address. Signs the transaction. The manager role is transferred from this address to `roles.manager` at the end. |
| `roles.manager`                 | `string`     | Yes      | Final Manager address after deployment                                                                                              |
| `roles.emergencyManager`        | `string`     | Yes      | Emergency Manager address                                                                                                           |
| `roles.rebalanceManager`        | `string`     | Yes      | Rebalance Manager address                                                                                                           |
| `roles.feeReceiver`             | `string`     | Yes      | Fee Receiver address                                                                                                                |
| `name`                          | `string`     | Yes      | Vault display name                                                                                                                  |
| `symbol`                        | `string`     | Yes      | dfToken symbol (e.g., `AIUSDC`)                                                                                                     |
| `vaultFee`                      | `number`     | Yes      | Vault fee in basis points. Note: this field is named `vaultFee` (not `vaultFeeBps`) for this endpoint.                              |
| `upgradable`                    | `boolean`    | Yes      | Whether the vault contract can be upgraded                                                                                          |
| `assets`                        | `Asset[]`    | Yes      | Assets to manage                                                                                                                    |
| `assets[].address`              | `string`     | Yes      | Token contract address                                                                                                              |
| `assets[].symbol`               | `string`     | Yes      | Human-readable token symbol                                                                                                         |
| `assets[].amount`               | `number`     | Yes      | Total deposit amount for this asset in stroops. Must be ≥ 1001 and equal to the sum of all strategy amounts.                        |
| `assets[].strategies`           | `Strategy[]` | Yes      | Strategies for this asset                                                                                                           |
| `assets[].strategies[].address` | `string`     | Yes      | Strategy contract address                                                                                                           |
| `assets[].strategies[].name`    | `string`     | Yes      | Strategy name                                                                                                                       |
| `assets[].strategies[].amount`  | `number`     | Yes      | Amount (in stroops) to invest into this strategy. The sum of all strategy amounts must equal `assets[].amount`.                     |

> **Strategy amounts must sum to the asset amount.** If `assets[0].amount = 10000000`, then all `strategies[].amount` values for that asset must add up to `10000000`.

### Response

```json theme={null}
{
  "xdr": "AAAAAgAAAAA...",
  "predictedVaultAddress": "CCQ2BCKKDX7HSF5TULLRFRKS4RYIC5ZZGYYTBR3XFDLZ6MMZFRJNXIEA",
  "warning": "The vault address is predicted from simulation. Actual address may differ if network state changes."
}
```

The `predictedVaultAddress` is derived from simulation and is accurate in most cases, but treat it as advisory until the transaction confirms on-chain.

***

## Complete Testnet Example (TypeScript)

This example deploys a BlendUSDC vault on testnet using the `create-vault-deposit` endpoint.

> **Before running**: Make sure you have BlendUSDC in your wallet. Go to [testnet.blend.capital](https://testnet.blend.capital), connect your Freighter wallet (on Testnet), and use the faucet to receive BlendUSDC.

```typescript theme={null}
const API_KEY = process.env.DEFINDEX_API_KEY!;
const DEPLOYER_ADDRESS = "GACKTN5D..."; // Your Stellar testnet address

const body = {
  roles: {
    manager: DEPLOYER_ADDRESS,
    emergencyManager: DEPLOYER_ADDRESS,
    rebalanceManager: DEPLOYER_ADDRESS,
    feeReceiver: DEPLOYER_ADDRESS,
  },
  vaultFeeBps: 100, // 1%
  assets: [
    {
      // BlendUSDC on testnet
      address: "CAQCFVLOBK5GIULPNZRGATJJMIZL5BSP7X5YJVMGCPTUEPFM4AVSRCJU",
      strategies: [
        {
          address: "CALLOM5I7XLQPPOPQMYAHUWW4N7O3JKT42KQ4ASEEVBXDJQNJOALFSUY",
          name: "Blend USDC Strategy",
          paused: false,
        },
      ],
    },
  ],
  name: "My USDC Vault",
  symbol: "MUSDC",
  upgradable: true,
  caller: DEPLOYER_ADDRESS,
  depositAmounts: [1001], // Minimum first deposit (1001 stroops)
};

// Step 1: Build the transaction
const res = await fetch(
  "https://api.defindex.io/factory/create-vault-deposit?network=testnet",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_KEY}`,
    },
    body: JSON.stringify(body),
  }
);
const { xdr } = await res.json();

// Step 2: Sign with your wallet (Freighter / Privy / Crossmint)
const signedXdr = await signTransaction(xdr, { network: "TESTNET" });

// Step 3: Submit
const sendRes = await fetch(
  "https://api.defindex.io/send?network=testnet",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_KEY}`,
    },
    body: JSON.stringify({ xdr: signedXdr }),
  }
);
const result = await sendRes.json();
console.log("Vault deployed:", result.txHash);
```

***

## Complete Mainnet Example (TypeScript)

```typescript theme={null}
const body = {
  roles: {
    manager: "GMANAGER...",
    emergencyManager: "GEMERGENCY...",
    rebalanceManager: "GREBALANCE...",
    feeReceiver: "GFEERECEIVER...",
  },
  vaultFeeBps: 50, // 0.5%
  assets: [
    {
      // Real USDC on mainnet (Circle / Stellar SAC)
      address: "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",
      strategies: [
        {
          address: "CDB2WMKQQNVZMEBY7Q7GZ5C7E7IAFSNMZ7GGVD6WKTCEWK7XOIAVZSAP",
          name: "Blend USDC Fixed Strategy",
          paused: false,
        },
      ],
    },
  ],
  name: "My USDC Vault",
  symbol: "MUSDC",
  upgradable: true,
  caller: "GDEPLOYER...",
  depositAmounts: [1001], // 0.0001001 USDC — the required minimum
};

const res = await fetch(
  "https://api.defindex.io/factory/create-vault-deposit?network=mainnet",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_KEY}`,
    },
    body: JSON.stringify(body),
  }
);
const { xdr } = await res.json();
// ... sign and send as above
```

***

## After Deployment: First Rebalance

After the vault is deployed and the first deposit is made, call the `rebalance` function to invest funds into your chosen strategies. Without this step, all deposited funds remain **idle** (uninvested) in the vault.

See the [Rebalance section in the main Create a Vault guide](/integration-guide/creating-a-defindex-vault/index#step-5-first-rebalance) for how to do this via the API or `stellar-cli`.

> If you used `create-vault-auto-invest`, the initial rebalance is already done for you as part of the deployment transaction.

***

## Testnet vs Mainnet Differences at a Glance

| Aspect              | Testnet                                                      | Mainnet                                          |
| ------------------- | ------------------------------------------------------------ | ------------------------------------------------ |
| USDC                | BlendUSDC (`CAQCFV...`) — get from testnet.blend.capital     | Circle USDC (`CCW67T...`)                        |
| CETES               | Testnet CETES (`CC72F5...`) — get from testnet.blend.capital | Real CETES token                                 |
| XLM                 | Testnet XLM — get from Friendbot                             | Real XLM                                         |
| Factory             | `CDSCWE4...`                                                 | `CDKFHFJ...`                                     |
| API `network` param | `testnet`                                                    | `mainnet`                                        |
| Network passphrase  | `Test SDF Network ; September 2015`                          | `Public Global Stellar Network ; September 2015` |
| RPC URL             | `https://soroban-testnet.stellar.org`                        | Provider-dependent                               |

***

## Troubleshooting

**`StrategyDoesNotSupportAsset` (error 102)**\
The strategy address you provided does not support the asset token you specified. Double-check that the strategy address matches the asset and the strategy/asset/network relation is correct. For example, the USDC strategy cannot be used with the XLM token address or, the USDC strategy on testnet cannot be used with the USDC token address from mainnet.

**Transaction fails with simulation error on testnet**\
You may not have a BlendUSDC trustline. Visit [testnet.blend.capital](https://testnet.blend.capital), connect your wallet, and add the BlendUSDC asset before trying again.

**`RolesIncomplete` (error 104)**\
All four roles (0–3) must be provided. If you leave any out, the factory will reject the transaction.

**`FeeTooHigh` (factory error 406)**\
The `vaultFeeBps` value exceeds the maximum allowed. Keep it at or below 9,000 (90% of yield).

**`AmountNotAllowed` (error 110)**\
The initial deposit amount is zero or negative. Provide at least 1001 stroops per asset.

For additional errors, see the [Troubleshooting Guide](/integration-guide/troubleshooting).