> ## Documentation Index > Fetch the complete documentation index at: https://docs.decibel.trade/llms.txt > Use this file to discover all available pages before exploring further. # Vault Integration Guide > Create and manage onchain vaults that pool capital under a single manager with interval-based performance fees and fungible share tokens. Vaults are onchain smart contracts that let you run a trading strategy with pooled capital. Contributors deposit USDC and receive fungible share tokens representing their claim on vault assets. You trade with the pooled funds and earn performance fees on profitable intervals. For how vaults work from a contributor's perspective, see [Vaults](/for-traders/vaults). For the protocol-owned liquidity vault, see [DLP Vault](/for-traders/dlp-vault). This guide walks you through creating a vault on testnet, funding it with USDC, and activating it for contributions. It then covers how vaults work under the hood (lifecycle, fees, shares) and advanced operations like contributing to existing vaults, redeeming shares, and delegating trading permissions. Fund your account, create a vault on testnet, and activate it. Lifecycle, fees, shares, and parameters. Contributing, redeeming, querying, and delegation. ## Part 1: Launch Your First Vault You can also create and manage vaults through the [Decibel UI](https://app.decibel.trade/accounts) without writing any code. Navigate to Accounts, then click the Vaults tab and "Create Vault." This guide covers the programmatic approach. ### 1. Prerequisites * [Node.js](https://nodejs.org/) 18+ (or Python 3.8+) * An API Wallet with its private key (create one at [app.decibel.trade/api](https://app.decibel.trade/api)) * An API Key (Bearer Token) from [Geomi](https://geomi.dev) (see [Get API Keys](/quickstart/node-api-key)) * Testnet APT for gas fees: paste your API Wallet address into the [Aptos Testnet Faucet](https://aptos.dev/network/faucet). This is your wallet address, not your Trading Account (subaccount) address. ### 2. Install Dependencies ```bash TypeScript theme={null} npm install @aptos-labs/ts-sdk ``` ```bash Python theme={null} pip install aptos-sdk ``` ### 3. Set Up Your Script Every code example in this guide uses these imports and constants: ```typescript TypeScript theme={null} import { Aptos, AptosConfig, Network, Account, Ed25519PrivateKey, AccountAddress, createObjectAddress, } from "@aptos-labs/ts-sdk"; // Testnet contract address const PACKAGE = "0xe7da2794b1d8af76532ed95f38bfdf1136abfd8ea3a240189971988a83101b7f"; // Derive USDC metadata address from the package const USDC_METADATA = createObjectAddress( AccountAddress.fromString(PACKAGE), new TextEncoder().encode("USDC"), ).toString(); const aptos = new Aptos(new AptosConfig({ network: Network.TESTNET })); const account = Account.fromPrivateKey({ privateKey: new Ed25519PrivateKey("0xYOUR_PRIVATE_KEY"), }); ``` ```python Python theme={null} from aptos_sdk.account import Account from aptos_sdk.account_address import AccountAddress from aptos_sdk.async_client import RestClient from aptos_sdk.bcs import Serializer from aptos_sdk.transactions import ( EntryFunction, TransactionArgument, TransactionPayload, ) import asyncio import json PACKAGE = "0xe7da2794b1d8af76532ed95f38bfdf1136abfd8ea3a240189971988a83101b7f" NODE_URL = "https://api.testnet.aptoslabs.com/v1" client = RestClient(NODE_URL) account = Account.load_key("0xYOUR_PRIVATE_KEY") ``` ### 4. Get Your Trading Account Address Your Trading Account (subaccount) holds USDC collateral. Use the onchain view function to get its address: ```typescript TypeScript theme={null} const [primarySubaccount] = await aptos.view({ payload: { function: `${PACKAGE}::dex_accounts::primary_subaccount`, typeArguments: [], functionArguments: [account.accountAddress.toString()], }, }); console.log("Primary subaccount:", primarySubaccount); ``` ```python Python theme={null} result = await client.view( f"{PACKAGE}::dex_accounts::primary_subaccount", [], [str(account.address())], ) primary_subaccount = json.loads(result)[0] print("Primary subaccount:", primary_subaccount) ``` The primary subaccount is auto-created on your first deposit. You don't need to create it manually. ### 5. Mint Testnet USDC On testnet, you can mint USDC using the `restricted_mint` function (rate-limited per account). You need at least 100 USDC to fund a vault. ```typescript TypeScript theme={null} const tx = await aptos.transaction.build.simple({ sender: account.accountAddress, data: { function: `${PACKAGE}::usdc::restricted_mint`, typeArguments: [], functionArguments: [ 500_000_000, // 500 USDC (6 decimals) ], }, }); const result = await aptos.signAndSubmitTransaction({ signer: account, transaction: tx, }); await aptos.waitForTransaction({ transactionHash: result.hash }); console.log("Minted USDC:", result.hash); ``` ```python Python theme={null} payload = EntryFunction.natural( f"{PACKAGE}::usdc", "restricted_mint", [], [TransactionArgument(500_000_000, Serializer.u64)], ) signed_txn = await client.create_bcs_signed_transaction( account, TransactionPayload(payload) ) txn = await client.submit_and_wait_for_bcs_transaction(signed_txn) print("Minted USDC:", txn["hash"]) ``` ### 6. Deposit USDC to Your Trading Account Move the USDC from your wallet into your Trading Account so it can be used as vault capital. ```typescript TypeScript theme={null} const tx = await aptos.transaction.build.simple({ sender: account.accountAddress, data: { function: `${PACKAGE}::dex_accounts_entry::deposit_to_subaccount_at`, typeArguments: [], functionArguments: [ primarySubaccount, // Trading Account address from step 4 USDC_METADATA, // USDC metadata address 200_000_000, // 200 USDC (6 decimals) ], }, }); const result = await aptos.signAndSubmitTransaction({ signer: account, transaction: tx, }); await aptos.waitForTransaction({ transactionHash: result.hash }); console.log("Deposited USDC:", result.hash); ``` ```python Python theme={null} usdc_metadata = AccountAddress.from_str( # Derive USDC metadata: createObjectAddress(PACKAGE, "USDC") "0xbdabb88aa9a875f3a2ebe0974e24f3ae5e57cfd17c6abdfef8a8111f43681b7e" ) payload = EntryFunction.natural( f"{PACKAGE}::dex_accounts_entry", "deposit_to_subaccount_at", [], [ TransactionArgument(AccountAddress.from_str(primary_subaccount), Serializer.struct), TransactionArgument(usdc_metadata, Serializer.struct), TransactionArgument(200_000_000, Serializer.u64), ], ) signed_txn = await client.create_bcs_signed_transaction( account, TransactionPayload(payload) ) txn = await client.submit_and_wait_for_bcs_transaction(signed_txn) print("Deposited USDC:", txn["hash"]) ``` ### 7. Create and Fund Your Vault This creates a new vault and deposits your initial capital from your Trading Account. If you fund with at least \$100, the vault activates automatically. ```typescript TypeScript theme={null} const tx = await aptos.transaction.build.simple({ sender: account.accountAddress, data: { function: `${PACKAGE}::vault_api::create_and_fund_vault`, typeArguments: [], functionArguments: [ primarySubaccount, // funded_from_dex_subaccount USDC_METADATA, // contribution_asset_type "My Trading Vault", // vault_name "Algorithmic strategy", // vault_description ["https://x.com/myvault", ""], // vault_social_links [xUrl, discordUrl] "MTV", // vault_share_symbol "", // vault_share_icon_uri "", // vault_share_project_uri 500, // fee_bps (5% performance fee) 2592000, // fee_interval_s (30 days in seconds) 0, // contribution_lockup_duration_s (no lockup) 200_000_000, // initial_funding (200 USDC, 6 decimals) true, // accepts_contributions true, // delegate_to_creator ], }, }); const result = await aptos.signAndSubmitTransaction({ signer: account, transaction: tx, }); await aptos.waitForTransaction({ transactionHash: result.hash }); console.log("Vault created:", result.hash); ``` ```python Python theme={null} payload = EntryFunction.natural( f"{PACKAGE}::vault_api", "create_and_fund_vault", [], [ TransactionArgument(AccountAddress.from_str(primary_subaccount), Serializer.struct), TransactionArgument(usdc_metadata, Serializer.struct), TransactionArgument("My Trading Vault", Serializer.str), TransactionArgument("Algorithmic strategy", Serializer.str), TransactionArgument(["https://x.com/myvault", ""], lambda s, v: s.sequence(v, Serializer.str)), TransactionArgument("MTV", Serializer.str), TransactionArgument("", Serializer.str), TransactionArgument("", Serializer.str), TransactionArgument(500, Serializer.u64), TransactionArgument(2592000, Serializer.u64), TransactionArgument(0, Serializer.u64), TransactionArgument(200_000_000, Serializer.u64), TransactionArgument(True, Serializer.bool), TransactionArgument(True, Serializer.bool), ], ) signed_txn = await client.create_bcs_signed_transaction( account, TransactionPayload(payload) ) txn = await client.submit_and_wait_for_bcs_transaction(signed_txn) print("Vault created:", txn["hash"]) ``` Setting `delegate_to_creator` to `true` automatically grants your account trading permissions on the vault. If you set it to `false`, you need to delegate separately later. For full parameter details, see [Create and Fund Vault](/developer-hub/on-chain/vault/create-and-fund). ### 8. Activate the Vault (if needed) If your vault was funded with at least \$100 at creation, it activates automatically. Otherwise, fund it to the minimum and then activate: ```typescript TypeScript theme={null} const tx = await aptos.transaction.build.simple({ sender: account.accountAddress, data: { function: `${PACKAGE}::vault_api::activate_vault`, typeArguments: [], functionArguments: [ vaultAddress, // Vault object address from the VaultCreatedEvent ], }, }); const result = await aptos.signAndSubmitTransaction({ signer: account, transaction: tx, }); await aptos.waitForTransaction({ transactionHash: result.hash }); console.log("Vault activated:", result.hash); ``` ```python Python theme={null} payload = EntryFunction.natural( f"{PACKAGE}::vault_api", "activate_vault", [], [TransactionArgument(AccountAddress.from_str(vault_address), Serializer.struct)], ) signed_txn = await client.create_bcs_signed_transaction( account, TransactionPayload(payload) ) txn = await client.submit_and_wait_for_bcs_transaction(signed_txn) print("Vault activated:", txn["hash"]) ``` For full parameter details, see [Activate Vault](/developer-hub/on-chain/vault/activate). ### 9. Delegate Trading (optional) If you set `delegate_to_creator` to `false` during creation, or want to grant trading permissions to another account (e.g. a bot wallet): ```typescript TypeScript theme={null} const tx = await aptos.transaction.build.simple({ sender: account.accountAddress, data: { function: `${PACKAGE}::vault_admin_api::delegate_dex_actions_to`, typeArguments: [], functionArguments: [ vaultAddress, // Vault object address botWalletAddress, // Address to delegate trading to null, // No expiration (or Unix timestamp in seconds) ], }, }); const result = await aptos.signAndSubmitTransaction({ signer: account, transaction: tx, }); await aptos.waitForTransaction({ transactionHash: result.hash }); console.log("Delegated trading:", result.hash); ``` ```python Python theme={null} def serialize_option_u64(ser, val): """Serialize an optional u64: None = empty option, int = some(value)""" if val is None: ser.u8(0) # None variant else: ser.u8(1) # Some variant ser.u64(val) payload = EntryFunction.natural( f"{PACKAGE}::vault_admin_api", "delegate_dex_actions_to", [], [ TransactionArgument(AccountAddress.from_str(vault_address), Serializer.struct), TransactionArgument(AccountAddress.from_str(bot_wallet_address), Serializer.struct), TransactionArgument(None, serialize_option_u64), # No expiration ], ) signed_txn = await client.create_bcs_signed_transaction( account, TransactionPayload(payload) ) txn = await client.submit_and_wait_for_bcs_transaction(signed_txn) print("Delegated trading:", txn["hash"]) ``` For full parameter details, see [Delegate DEX Actions](/developer-hub/on-chain/vault/delegate-dex-actions). ### 10. Place an Order as the Vault With delegation set up, place orders on behalf of the vault using the same [order placement flow](/developer-hub/on-chain/order-management/place-order). The vault's pooled capital is used as margin. Verify your vault is live. Browse to [app.decibel.trade/vaults](https://app.decibel.trade/vaults) and search for your vault name. You can also query it via the REST API to confirm it's active and accepting contributions. ## Part 2: How Vaults Work A vault pools capital under a single manager. The manager trades with the pooled funds, and profits (after fees) are distributed to all shareholders proportionally. Contributors receive fungible share tokens representing their claim on the vault's net assets. See [Vaults for Traders](/for-traders/vaults) for the full contributor perspective. ### Vault Lifecycle | Phase | What happens | | -------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Creation | Manager creates the vault, sets fee parameters, and deposits initial capital | | Pre-activation | Vault exists but doesn't accept contributions. Manager must fund it to the minimum (\$100) | | Activation | Manager activates the vault (or it auto-activates if funded with >= \$100 at creation). It can now accept outside contributions | | Active trading | Manager (or delegate) trades with pooled capital. Contributors can join or redeem | | Ongoing | Fees are crystallized at each interval. Shares are minted/burned as contributors join/leave | ### Interval-Based Performance Fees Vaults use an interval-based fee model. There is no high watermark or cumulative tracking. 1. When a vault is created, the manager sets a fee rate (0-10%) and a fee interval (30-365 days). 2. At the end of each interval, the protocol compares the vault's current NAV to its NAV at the start of that interval. 3. If the vault profited during that interval, the manager receives their fee percentage as newly minted shares. 4. If the vault lost money or broke even, the manager receives nothing for that interval. 5. The next interval starts fresh. There is no carry-forward of losses from previous intervals. Each interval is independent. If a vault loses 20% in one interval and gains 25% in the next, the manager earns fees on the full 25% gain in the second interval, even though the vault hasn't fully recovered. This is different from a high watermark model. ### Key Parameters These are the protocol-enforced limits. Vault managers choose values within these ranges at creation time. | Parameter | Range / Value | | ----------------------- | -------------------------------------- | | Performance fee | 0-10% (0-1000 bps) | | Fee interval | 30-365 days | | Min manager capital | Lesser of 5% of vault NAV or \$100,000 | | Min activation funding | \$100 | | Min contribution | \$10 | | Min redemption | \$5 | | Max contribution lockup | 0-7 days | | Vault creation fee | Configurable (currently \$0) | ### Shares as Fungible Tokens When you contribute to a vault, you receive fungible share tokens on Aptos. These shares are transferable, can be used as collateral in other DeFi protocols, and can be traded on secondary markets. See [Fungible Token Ownership](/for-traders/vaults#fungible-token-ownership) for details. ### Protocol Vault (DLP) vs User Vaults Decibel runs one special vault, the [Decibel Liquidity Provider (DLP)](/for-traders/dlp-vault), alongside user-created vaults. Both use the same onchain infrastructure. | | DLP Vault | User Vaults | | ------------------- | -------------------- | ----------------------------- | | Manager | Protocol (automated) | Any user | | Strategy | Market making | Manager's discretion | | Contribution lockup | 72 hours | 0-7 days (manager-configured) | | Fee structure | 0% | Manager-defined (0-10%) | ## Part 3: Advanced Operations ### Contributing to an Existing Vault Anyone can contribute to an active vault that accepts contributions. The minimum contribution is \$10 USDC. Contributions go through your Trading Account (subaccount). ```typescript TypeScript theme={null} const tx = await aptos.transaction.build.simple({ sender: account.accountAddress, data: { function: `${PACKAGE}::dex_accounts_entry::contribute_to_vault`, typeArguments: [], functionArguments: [ primarySubaccount, // Your Trading Account (Object) vaultAddress, // Vault address USDC_METADATA, // USDC metadata address 50_000_000, // 50 USDC (6 decimals) ], }, }); const result = await aptos.signAndSubmitTransaction({ signer: account, transaction: tx, }); await aptos.waitForTransaction({ transactionHash: result.hash }); console.log("Contributed to vault:", result.hash); ``` ```python Python theme={null} payload = EntryFunction.natural( f"{PACKAGE}::dex_accounts_entry", "contribute_to_vault", [], [ TransactionArgument(AccountAddress.from_str(primary_subaccount), Serializer.struct), TransactionArgument(AccountAddress.from_str(vault_address), Serializer.struct), TransactionArgument(usdc_metadata, Serializer.struct), TransactionArgument(50_000_000, Serializer.u64), ], ) signed_txn = await client.create_bcs_signed_transaction( account, TransactionPayload(payload) ) txn = await client.submit_and_wait_for_bcs_transaction(signed_txn) print("Contributed to vault:", txn["hash"]) ``` If the vault has a contribution lockup configured, you cannot redeem your shares until the lockup period expires. For full parameter details, see [Contribute to Vault](/developer-hub/on-chain/vault/contribute). ### Redeeming Shares To withdraw from a vault, redeem your share tokens for the underlying USDC. The minimum redemption is \$5. The protocol may close up to 10% of positions per redemption at up to 2% slippage to free capital. ```typescript TypeScript theme={null} const tx = await aptos.transaction.build.simple({ sender: account.accountAddress, data: { function: `${PACKAGE}::dex_accounts_entry::redeem_from_vault`, typeArguments: [], functionArguments: [ primarySubaccount, // Your Trading Account (Object) vaultAddress, // Vault address 10_000_000, // Shares to redeem (6 decimals) ], }, }); const result = await aptos.signAndSubmitTransaction({ signer: account, transaction: tx, }); await aptos.waitForTransaction({ transactionHash: result.hash }); console.log("Redeemed from vault:", result.hash); ``` ```python Python theme={null} payload = EntryFunction.natural( f"{PACKAGE}::dex_accounts_entry", "redeem_from_vault", [], [ TransactionArgument(AccountAddress.from_str(primary_subaccount), Serializer.struct), TransactionArgument(AccountAddress.from_str(vault_address), Serializer.struct), TransactionArgument(10_000_000, Serializer.u64), ], ) signed_txn = await client.create_bcs_signed_transaction( account, TransactionPayload(payload) ) txn = await client.submit_and_wait_for_bcs_transaction(signed_txn) print("Redeemed from vault:", txn["hash"]) ``` For full parameter details, see [Redeem from Vault](/developer-hub/on-chain/vault/redeem). ### Querying Vault Data Vault data is available through the REST API. See the [vault endpoints](/api-reference/vaults/get-account-owned-vaults) for querying vault data like ownership, performance, and public vault listings. ### Trading on Behalf of a Vault The vault manager (or any delegated account) can place orders using the vault's pooled capital: 1. At creation: if `delegate_to_creator` is `true`, the vault creator automatically has trading permissions. 2. After creation: the vault owner can delegate to additional accounts using `delegate_dex_actions_to`. 3. Delegations can optionally have an expiration timestamp. 4. The vault owner can revoke delegations at any time. Once delegated, the account can place orders, manage positions, and execute trades using the vault's capital. The same order types available to regular [Trading Accounts](/for-traders/vaults) (limit, market, TWAP, bulk) work for vaults. ## What's Next Full parameter docs for [Create and Fund](/developer-hub/on-chain/vault/create-and-fund), [Activate](/developer-hub/on-chain/vault/activate), [Contribute](/developer-hub/on-chain/vault/contribute), [Redeem](/developer-hub/on-chain/vault/redeem), and [Delegate](/developer-hub/on-chain/vault/delegate-dex-actions). See [Vaults for Traders](/for-traders/vaults) for the contributor perspective and [Fees](/for-traders/fees) for the full fee breakdown. Learn about the protocol-owned liquidity vault and its backstop role on the [DLP Vault](/for-traders/dlp-vault) page. The [TypeScript SDK](/typescript-sdk/overview) provides high-level helpers for vault operations.