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 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.

`POST /factory/create-vault`

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

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

Request Body

{
  "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

{
  "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.

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

Request Body

{
  "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:

{
  "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.

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

Request Body

{
  "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

{
  "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, connect your Freighter wallet (on Testnet), and use the faucet to receive BlendUSDC.

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)

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 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, 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.

Getting Started

Integration Guide

Stable APY & Boosts

Strategies

Advanced Documentation

Contact us

Quick Reference: Contract Addresses

Testnet

Mainnet

`POST /factory/create-vault`

Request Body

Field Reference

Response

`POST /factory/create-vault-deposit`

Request Body

Additional Field

Response

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

Request Body

Field Reference

Response

Complete Testnet Example (TypeScript)

Complete Mainnet Example (TypeScript)

After Deployment: First Rebalance

Testnet vs Mainnet Differences at a Glance

Troubleshooting

​Quick Reference: Contract Addresses

​Testnet

​Mainnet

​POST /factory/create-vault

​Request Body

​Field Reference

​Response

​POST /factory/create-vault-deposit

​Request Body

​Additional Field

​Response

​POST /factory/create-vault-auto-invest

​Request Body

​Field Reference

​Response

​Complete Testnet Example (TypeScript)

​Complete Mainnet Example (TypeScript)

​After Deployment: First Rebalance

​Testnet vs Mainnet Differences at a Glance

​Troubleshooting

Quick Reference: Contract Addresses

Testnet

Mainnet

`POST /factory/create-vault`

Request Body

Field Reference

Response

`POST /factory/create-vault-deposit`

Request Body

Additional Field

Response

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

Request Body

Field Reference

Response

Complete Testnet Example (TypeScript)

Complete Mainnet Example (TypeScript)

After Deployment: First Rebalance

Testnet vs Mainnet Differences at a Glance

Troubleshooting