# Velvet: SocialFAI Ecosystem
Velvet is an onchain trading ecosystem that combines AI, social intelligence, and multi-chain execution. Traders use Velvet to discover opportunities, analyze them with AI, and execute across chains - all from a self-custodial wallet.
The platform spans a consumer trading app, an AI framework, and white-label infrastructure forming a unified SocialFAI (Social + Decentralized Finance + AI) stack. There are five ways to use Velvet:
***
#### **1. VelvetX**
VelvetX is Velvet's flagship SocialFAI trading app, currently in invite-only early access.
It combines cross-chain spot and perpetuals trading, smart wallet and KOL tracking across 13M+ indexed wallets, a social feed, an integrated AI copilot, and fee cashback and rewards programs in a single interface.
Best for: Active traders who want discovery, social intelligence, AI analysis, and execution in one app.
***
#### **2. Trading Terminal**
The Velvet Trading Terminal is the previous generation of the Velvet app. It remains live and publicly accessible, offering spot, perps, Trenches, yield, and advanced order types across multiple chains.
New features ship to VelvetX first; the Trading Terminal continues to be supported for existing users.
Best for: Existing users of the public terminal, and anyone who wants access without an invite code.
***
#### **3. AI Framework**
Velvet's multi-agent AI system powers analysis and execution across the platform. Users can research tokens, evaluate risk and momentum, and prepare or execute trades through natural language — with all actions initiated and controlled by the user.
Best for: Traders and researchers who want AI-assisted analysis and execution inside their workflow.
***
#### **4. Onchain Vaults**
Velvet's vault contracts let traders and communities create shared onchain portfolios with transparent, verifiable execution. Depositors and managers interact with the same smart contracts; assets remain non-custodial throughout. Vaults are created and operated by their creators; Velvet provides the infrastructure.
Best for: Onchain communities and groups that want transparent, shared execution with verifiable track records.
***
#### **5. Custom App (White-Label Infrastructure)**
Teams can launch fully branded trading applications on Velvet's execution engine, AI stack, and backend systems — under their own domain, without building core infrastructure from scratch.
Best for: Crypto projects and platforms bringing onchain trading products to their own users.
*Velvet is self-custodial software and does not provide investment advice. See our* [*Terms of Service*](https://www.velvet.capital/terms-of-service.html) *for eligibility and jurisdictional restrictions.*\
# VelvetX
VelvetX is Velvet's SocialFAI (Social + Finance + AI) trading application: a single interface for discovering, analyzing, and executing onchain trades, powered by social and wallet intelligence and boosted by AI.
The app combines cross-chain spot trading, perpetual futures, smart wallet and KOL tracking across 13M+ indexed wallets, an AI trading copilot, and a rewards program — all from a self-custodial wallet.
VelvetX is currently in invite-only early access. Access the app at[ x.velvet.capital](https://x.velvet.capital/).
#### Access
VelvetX is rolling out gradually through invite codes. Existing users receive codes to share, and codes are distributed through the Velvet community.
To request access, join the[ Velvet community](https://docs.velvet.capital/links) and ask the team for an invite code, or use a code shared by an existing user.
VelvetX is available on desktop and mobile browsers, and can be installed directly to your iPhone or Android Home Screen as an app.
#### Explore
Trending tokens across every supported chain surface in a single, unified view, so you don't have to switch networks to see where the action is.
Views include Trending, New Pairs, Top Gainers, and Highest Volume, with configurable filters aggregated across all chains at once, or narrowed down to one.
#### Trading
VelvetX supports spot trading across Solana, Base, BNB Chain, Robinhood, Ethereum, Sonic, and additional networks as they are added.
Cross-chain swaps are handled natively: select any asset on a supported chain and trade into assets on another chain from the same panel, with routing handled automatically. Velvet covers the gas fees on cross-chain swaps, so you can move value across chains without holding native gas tokens on the destination network. Typical cross-chain execution completes in seconds.
Execution options include:
* Instant Buy/Sell for instant one-click execution at a preset trade size.
* Market for custom amount.
* Swap for full control with a quote preview before execution.
* TP/SL, Limits, DCA, Wallet Buys and Sells (automatically mirroring a followed wallet's trades), and other advanced orders for automated position management.
VelvetX also integrates top launchpads including Pumpfun, Bankr, and 10+ other popular platforms, so newly launched assets can be discovered and traded across their full lifecycle, including on the bonding curve.
#### Perpetual Futures
Perps are fully integrated into VelvetX, with access to crypto, stocks, and commodities markets at up to 50x leverage.
The perps experience includes one-click gasless deposits from other chains, position management tools, and Take Profit / Stop Loss orders. Hyperliquid serves as the execution layer, with access extending to builder-deployed HIP-3 markets as they come online.
Leveraged trading involves significant risk, including loss of deposited collateral. Users are responsible for their own positions and risk management.
#### Discovery & Social Intelligence
VelvetX indexes more than 13 million smart wallets and KOL accounts, linking onchain activity to social identity.
This powers:
* Smart wallet and KOL tracking: follow what top traders are accumulating as it happens onchain.
* Trader leaderboards: browse and rank wallets by PnL, win rate, and trade history to see who's actually making money onchain, then copy trade them directly so their new positions mirror into your own wallet, sized according to your own rules.
* Trending, New Pairs, Top Gainers, and Highest Volume market views with configurable filters.
* Watchlists/Following for both tokens and traders.
A social feed is rolling out progressively as part of the SocialFAI experience: live buy and sell activity from wallets you follow, posts, PnL share cards, and AI-generated insights, alongside the ability to post your own analysis, react, and comment.
#### AI Copilot
Velvet Unicorn is integrated directly into VelvetX as a trading copilot.
Users can prompt it to analyze tokens, research opportunities, evaluate risk and momentum, and prepare or execute trades. The copilot operates on user instruction — analysis and execution are initiated and controlled by the user from within the app.
#### Rewards
VelvetX includes promotional reward programs for active users:
* Cashback: up to 100% of trading fees returned, per current program terms.
* Velvet Gems: onchain activity (trading, staking, referrals) earns Gems that determine allocations from periodic $VELVET reward pools.
Reward programs are promotional, run in epochs, and are subject to program terms, which may change between epochs. Details for the current epoch are announced on official Velvet channels.
#### Self-Custody
VelvetX is non-custodial. Trades execute directly from the user's wallet; the Company does not take custody of user assets. Embedded wallets are secured through Turnkey infrastructure, and users may also connect existing external wallets.
#### My Positions
The My Positions view brings together all tokens, perpetual positions, and DeFi positions held in your wallet in one place. Monitor holdings, open charts, add favorites, and adjust or close positions instantly, without leaving the app.
#### Getting Started
1. Go to[ x.velvet.capital](https://x.velvet.capital/) and enter your invite code.
2. Sign in and create or connect a wallet.
3. Fund your wallet on any supported chain.
4. Explore Trending, follow smart wallets, or ask the AI copilot where to start.
5. Trade anything.
# Trading Terminal
> The Trading Terminal is the previous generation of the Velvet app. It remains live and publicly accessible at [dapp.velvet.capital](https://dapp.velvet.capital/). New features ship first to VelvetX, Velvet's current flagship app.
The Velvet Trading Terminal allows you to trade spot assets, perpetuals, or access DeFi pools directly from your wallet across multiple chains. No deposits or custodial transfers are required.
Start by selecting your preferred chain, including Base, BNB Chain, Solana, Hyperliquid, Ethereum, Monad, and Sonic, with additional networks continuously being added. Once selected, you can explore market views such as Trending, New Pairs, Top Gainers, and Highest Volume, with configurable filters and parameters.
***
#### Trading
There are multiple ways to execute spot trades within the terminal, depending on the level of speed or control you need.
Turbo Buy enables instant execution. Set your trade size once, then click the lightning icon next to any token to execute immediately.
Trade Module provides full control. Clicking the trade arrows beside a token loads it into the trading panel, where you can preview routing, adjust amounts, and execute the swap.
You can also open a token’s detailed page to view charts, onchain analytics, and live transactions. From there, you can trade into the token from any asset on that chain using the trading panel.
***
#### Perps
Velvet integrates Hyperliquid directly into the Trading Terminal, allowing users to trade perpetual futures from the same interface used for spot and yield. Instead of managing perpetuals on a separate platform, users can access them as part of a unified trading and portfolio workflow inside Velvet.
Hyperliquid serves as the execution layer for perpetuals, bringing a fully onchain order book, a unified perp trading API, and an expanding perp ecosystem through HIP-3 builder-deployed markets. Through Velvet, perpetuals become part of a broader portfolio view rather than an isolated trading activity.
This expands what can be traded inside Velvet beyond crypto spot and DeFi positions. With Velvet Perps, users can trade perpetual futures referencing crypto, equity, and commodity prices.
Velvet’s perps experience also extends into the broader HIP-3 ecosystem, including protocols such as Trade\[XYZ], Dreamcash, HyENA, Kinetiq, and other builder-deployed perpetual markets as they come online. This gives users access to a wider range of perp opportunities through the same Velvet trading workflow.
***
#### Trenches
The Trenches section is designed for trading newly launched tokens across Base, Solana, and BNB Chain from a single interface.
Velvet integrates more than 40 launchpads, allowing users to discover and trade new launchpad assets without needing to jump across different platforms or workflows. Users can trade across the full lifecycle of a launch, including directly on the bonding curve as new assets begin trading.
The interface includes filters to help identify promising opportunities faster, making it easier to sort through high volumes of new launches and focus on the tokens that match a user’s preferred setup or strategy.
Velvet Unicorn AI also helps users analyze new launches by surfacing insights around token activity, momentum, and market context directly inside the trading workflow.
This makes Trenches the easiest way to discover, analyze, and trade newly launched assets across Base, Solana, and BNB Chain from one unified terminal.
***
#### Advanced Order Types
Velvet supports advanced execution tools for users who want more automation and precision.
TP/SL (Take Profit / Stop Loss) allows users to define exit levels in advance so positions can be closed automatically when price targets or risk thresholds are reached.
DCA (Dollar Cost Averaging) automates recurring buys or sells over time to reduce entry volatility and accumulate or exit positions gradually.
Limit Orders allow users to set a target price at which they want to buy or sell. The trade executes automatically once market conditions reach the specified level.
Wallet Buys and Sells trigger trades based on the onchain activity of specific wallets such as developers, funds, or whales. When the tracked wallet buys or sells a token, Velvet can automatically mirror the action according to the user’s defined sizing and rules.
***
#### AlphaHub
AlphaHub surfaces real-time market signals generated by Velvet Unicorn AI, focused on high-momentum memecoins and early-stage tokens.
Over 20 live screening strategies continuously scan markets and flag tokens exhibiting statistical patterns associated with momentum or breakout behavior. Users can subscribe to individual strategies and receive alerts when new signals appear.
AlphaHub signals are informational screening outputs, not recommendations to buy or sell any asset. Signals reflect historical statistical patterns, which do not predict future results - particularly in newly launched and low-liquidity tokens, which carry elevated risk including total loss.
***
#### Yield
The Yield section provides direct access to integrated DeFi pools across supported chains.
You can browse opportunities by APY, TVL, and protocol, or search specific pools. Velvet integrates dozens of DeFi protocols, allowing you to enter or exit positions from the same execution panel used for trading.
When depositing into a pool, the resulting position token is held directly in your wallet.
***
#### My Positions
The My Positions tab provides a unified view of all tokens, perpetual positions, and DeFi positions held in your wallet.
From this view you can monitor holdings, open charts, add favorites, or execute buy and sell actions instantly. Positions can be adjusted or closed without leaving the terminal, enabling continuous portfolio management from a single interface.
# AI Framework
Velvet’s AI framework is the intelligence layer of the platform. It has two core components:
* **Velvet Unicorn (VU)** — a multi-agent AI framework that powers research, market intelligence, and user-directed execution across the platform. The framework contains the skills, tools, and plugins to deliver fast, real-time information about current crypto-market conditions.
* **Velvet-1** — Velvet’s crypto-native AI model, trained on crypto and onchain data and integrated with tools from Velvet Unicorn and beyond, to power the framework’s intelligence — spanning onchain analysis, raw onchain data graph analysis, and CEX market data.
All actions are initiated and controlled by the user.
### Velvet Unicorn (VU)
Velvet Unicorn is the AI assistant at the heart of the Velvet DeFAI ecosystem. It combines onchain data, market intelligence, and execution capabilities into a unified agent system that analyzes opportunities, generates insights, and executes user-requested actions through natural language.
#### Architecture: a multi-agent system
Every VU request is routed through a multi-stage agent pipeline. A router first classifies the query and hands it to the right specialist — token analysis, wallet analysis, swap, trending, and dedicated pipelines for Hyperliquid, top-trader data, and the Virtuals ecosystem. For deep analysis, specialist agents run in parallel: a technical analyst for price and volume data, a sentiment agent for social and news coverage, and a fundamentals agent for tokenomics and protocol context.
Alongside the large LLM-based reasoning agents, the system uses smaller, custom-built, task-specific models (non-LLM) for precision functions such as statistical market prediction and classification. This hybrid design reduces the hallucination risk that makes general-purpose AI unreliable in financial contexts.
The system improves through a structured evaluation process: outputs and execution outcomes are measured against results, and the team uses this feedback — drawn from both onchain and social data — to refine agent routing, prompts, workflows, and model accuracy over time.
#### What VU can do
* **Research & discovery** — trending-token discovery from a plain-language instruction: filter by chain, category, launch date, volume patterns, and social activity, with key metrics and an AI summary for each result.
* **Token analysis** — full multi-agent analysis of any token (by symbol, contract address, or plain-language name; chain auto-detected), combining onchain data, price history, liquidity depth, social sentiment, and top-holder activity into a single structured report.
* **Wallet & portfolio analysis** — open-ended questions about any EVM or Solana wallet: performance, PnL history, top positions, trading frequency, risk exposure, and cross-chain activity — useful for due diligence and copy-trading research.
* **Market intelligence** — real-time insights from onchain, market, and social data; AI-generated market observations and news digests are surfaced in the Velvet feed.
* **Execution** — intent-based commands that go from analysis to action. A natural-language instruction like “swap 0.5 ETH for USDC” is resolved into tokens and the best available quote among integrated sources, returned as a ready-to-sign transaction that executes from the user’s own wallet. Swap execution is supported on Ethereum, Base, Solana, and BNB Chain.
* **Platform assistance** — help navigating Velvet, campaigns (staking, Gems), and troubleshooting.
VU’s market intelligence spans all chains supported by the platform, with dedicated coverage for Hyperliquid queries. Natural-language swap execution currently covers Ethereum, Base, Solana, and BNB Chain, and Prompt-to-Strategy runs on Base.
#### Build with VU: API, MCP, and Prompt-to-Strategy
The Velvet Unicorn agent portal opens the intelligence layer to builders and other AI agents:
* **API access** — developers and AI agents can call VU’s endpoints directly (token analysis, trending, wallet analysis, swaps, and open-ended chat). Two ways to pay: sign up for an API key with 1,000 free requests, or go accountless with x402, Coinbase’s open payment protocol for AI agents — the API responds with an HTTP 402 payment request, and the agent pays per call in stablecoins directly over HTTP. VU is also registered on the Virtuals Agent Commerce Protocol (ACP), so autonomous agents can discover, hire, and pay it onchain.
* **MCP support** — the same capabilities are exposed as native MCP tools for Claude Code, Codex, and any MCP client, plugging DeFi intelligence directly into agent-native environments.
* **Prompt-to-Strategy** — turn natural-language ideas into live, running DeFi strategies. An agent builds a structured strategy spec (rebalances, DCA, scheduled sells, and more), resolves tokens to contract addresses, preflights it against the account’s wallet, and deploys it. Velvet injects the spec into an audited execution template and launches it as a live process, with status, an onchain action log, and a stop control — every transaction signed by the account’s own non-custodial wallet. Strategies execute only the rules defined by the user; Velvet does not select, manage, or adjust strategies on a user’s behalf.
Explore the agent portal: [vu.velvetdao.xyz/agent](https://vu.velvetdao.xyz/agent/) — including an in-browser playground where signing up creates a non-custodial wallet and a free API key automatically.
Read more: [Velvet Unicorn AI Goes Live on x402](https://blog.velvet.capital/p/velvet-unicorn-ai-goes-live-on-x402)
### Velvet-1
Velvet-1 is Velvet’s crypto-native AI model, developed by the Velvet team and trained on crypto and onchain data to serve as the model layer of the Velvet AI framework.
* **Purpose-built for crypto.** Velvet-1 is trained on crypto-native data — onchain data, market data, and social data — so it understands tokens, onchain markets, and DeFi context natively.
* **Powers the Velvet AI framework.** Velvet-1 works inside the VU agent system — including the VU MCP and Prompt-to-Strategy — as the model layer behind research, market intelligence, and strategy generation.
#### Why crypto needs its own model
Onchain analysis has remained largely unsolved for AI. Today’s AI models excel at reasoning over static information such as code, documentation, books, and web pages. Unlike text, blockchain data is naturally represented as massive, interconnected graphs: every wallet, transaction, smart contract, protocol, liquidity pool, and token is connected to countless others through relationships that are constantly changing.
Those graphs evolve every second as new transactions settle, liquidity moves, positions open and close, and entirely new networks of interactions emerge. To truly understand what’s happening onchain, an AI model can’t simply retrieve information. It needs to reason over evolving graph structures — to understand the full context of onchain activity, market structure, and social dynamics as one interconnected, continuously evolving system.
Building a model capable of this kind of reasoning involves large volumes of onchain data and extensive research into new layers, context mechanisms, and training techniques designed specifically for continuously evolving onchain environments.
### Non-custodial by design
Across the framework, AI never takes custody of user assets. In the terminal, VU executes from the user’s own connected wallet through the Velvet execution engine; API swap calls return a ready-to-sign transaction that the user’s wallet submits; and Prompt-to-Strategy strategies sign every transaction with the account’s own non-custodial wallet, created during onboarding.
> Velvet’s AI features are tools for research and execution — they are not financial advice, and outputs are not recommendations to buy or sell any asset. AI can make mistakes; always do your own research. See our [Terms of Service](https://www.velvet.capital/terms-of-service.html) for eligibility and jurisdictional restrictions.
# Onchain Vaults
Velvet's vault contracts allow users to create shared onchain portfolios. A vault is a set of smart contracts deployed by its creator: depositors mint vault tokens against their deposits, the vault creator executes trades within the vault's rules, and all activity is verifiable onchain. Assets remain non-custodial at all times - the vault creator never takes custody of depositor funds, and depositors can withdraw according to the vault's parameters.
Vaults can be private (personal use) or public (open to others, with optional whitelists). All performance history is recorded onchain and visible to anyone.
Vault creators configure their own vault parameters, including optional fees, at deployment. Velvet provides the software and smart contract infrastructure; it does not operate, manage, or promote any vault, and does not provide investment advice. Vault creators and depositors are solely responsible for their own decisions and for compliance with the laws of their jurisdictions.
To create one, click “Portfolios” in the menu.
Then select Public Portfolio on the right.
From there you will be taken through six steps for setting up and deploying the Public Portfolio.
1. Basic Info: Set the Portfolio Name, Ticker (what it will show up as in your wallet), Creator Name, and a description (to let others know the strategy you will be running)
2. Settings: Here you will set the portfolio visibility, Transfer Restriction (whether people can send the portfolio tokens to others or not), and Whitelisting (where you can decide who is able to join the portfolio)
3. Fees: Here you can configure optional vault fees - Management (an annualized % of vault TVL), Performance (a % of realized gains above the high-water mark), and Entry/Exit fees (a % of each deposit or withdrawal).
4. Token Set Up: This step is where you set the initial amount of tokens created and the minimum amount needed to deposit.
5. Asset Configuration: On this step, you will choose the assets you want in your portfolio. These assets can be spot assets or DeFi pools. This will just be the initial configuration and can be changed by trading in your portfolio once you have made the initial deposit. You can also just create it with one token (e.g., USDC or ETH) as a starting point for your strategy. Asset whitelisting will restrict your strategy only to the token you whitelist and can't be changed after the vault is created.
6. Review: Now everything is set up, you just have to review the Portfolio settings, press deploy (and confirm the transactions), and then make your initial deposit.
Once the portfolio is deployed you can go to “My Portfolio” to find it (will also be on the Marketplace if it is Public) and go to the portfolio page to run your strategy. You can trade tokens and manage DeFi positions within your portfolio by using the trade section on the right.
The fees you set up for the vault can be claimed by pressing “Claim Fees” at the bottom of the vault page. You can also change the fees by pressing "edit", they will only be changed after a 30-day cooldown period to give the depositors time to exit the vault before the fees change.
# Intent Execution API (Trading & DeFi)
### Overview
The Intent Execution API helps streamline onchain trading and DeFi interactions (e.g., entering LP positions) by using professional solvers and market makers. It aggregates the best available quotes and provides the necessary data for execution.
***
### Endpoint Details
* **URL:** `https://metasolvertest.velvetdao.xyz/best-quotes`
* **Method:** `POST`
***
### Request Details
#### Headers
Ensure to include the following header in your request:
* **Content-Type:** `application/json`
#### Body Parameters
The request body should be a JSON object containing the following fields:
| Parameter | Type | Required | Description |
| ---------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `amount` | `string` | Yes | The amount of tokens to swap or deposit, specified in the smallest units of the token (e.g., `"1000000"` for 1 token with 6 decimals). |
| `chainId` | `integer` | Yes | The unique identifier of the blockchain network (e.g., `8453` for the Base network). |
| `receiver` | `string` | Yes | The Ethereum address of the recipient. Must be a valid wallet address (e.g., `"0x3C96e2Fc58332746fbBAB5eC44f01572F99033ed"`). |
| `sender` | `string` | Yes | The Ethereum address of the sender. Must be a valid wallet address. |
| `slippage` | `string` | Yes | Acceptable slippage percentage for the transaction (e.g., `"1"` for 1%). |
| `tokenIn` | `string` | Yes | The contract address of the input (source) ERC-20 token. |
| `tokenOut` | `string` | Yes | The contract address of the output (destination) ERC-20 token or LP token in case of DeFi interactions. |
| `skipSimulation` | `boolean` | Yes | Whether to skip simulation of the transaction (`true` or `false`). |
#### Sample Request
```json
jsonCopy code{
"amount": "1000000",
"chainId": 8453,
"receiver": "0x3C96e2Fc58332746fbBAB5eC44f01572F99033ed",
"sender": "0x3C96e2Fc58332746fbBAB5eC44f01572F99033ed",
"slippage": "1",
"tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"tokenOut": "0x50c5725949a6f0c72e6c4a641f24049a917db0cb",
"skipSimulation": true
}
```
***
### Response Details
The API responds with a JSON object containing the best quotes from solvers and market makers, along with the necessary data to execute the intended trade or DeFi interaction.
#### Sample Response
```json
jsonCopy code{
"quotes": [
{
"protocol": "enso",
"to": "0xfDAc2748713906ede00D023AA3E0Cc893828D30B",
"data": "0x6fb0416800000000...",
"value": "0",
"amountOut": "1000480056413605717",
"minAmountOut": "990475255849469660",
"gasEstimate": 335931,
"simulationStatus": true,
"priceImpactPercentage": 0
},
{
"protocol": "barter",
"to": "0xfDAc2748713906ede00D023AA3E0Cc893828D30B",
"data": "0x6fb0416800000000...",
"value": "0x0",
"amountOut": "1000458532195358828",
"minAmountOut": "990453946873405240",
"gasEstimate": 342824,
"simulationStatus": true,
"priceImpactPercentage": "0.05"
}
],
"approvalAddress": "0xfDAc2748713906ede00D023AA3E0Cc893828D30B"
}
```
#### Response Parameters
* **quotes:** An array of quote objects from different solvers and market makers, sorted in descending order of `amountOut`.
Each quote object contains:
| Parameter | Type | Description |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------------ |
| `protocol` | `string` | Name of the protocol providing the quote (e.g., `"enso"`, `"barter"`). |
| `to` | `string` | The address to which the transaction data should be sent. |
| `data` | `string` | The calldata required to execute the transaction (trade or DeFi interaction). |
| `value` | `string` | The amount of Ether to send with the transaction (usually `"0"` for token swaps). |
| `amountOut` | `string` | The expected amount of output tokens or LP tokens from the interaction, in smallest units. |
| `minAmountOut` | `string` | The minimum acceptable amount of output tokens after accounting for slippage. |
| `gasEstimate` | `integer` | Estimated gas units required to execute the transaction. |
| `simulationStatus` | `boolean` | Indicates if the transaction simulation was successful (`true` or `false`). |
| `priceImpactPercentage` | `string` or `number` | The percentage price impact of the transaction (e.g., `"0.05"`). |
* **approvalAddress:** The address to which the input token (`tokenIn`) must be approved for the transaction to execute.
***
### Approval Process
Before executing the transaction, you must approve the `approvalAddress` to spend the input tokens (`tokenIn`) on your behalf.
#### Sample Approval Code (JavaScript)
```javascript
javascriptCopy codeconst Erc20Instance = new web3.eth.Contract(erc20Abi, tokenIn);
await Erc20Instance.methods
.approve(
response.approvalAddress,
approvalAmount
)
.send({
from: userAddress,
gas: gasAmount,
gasPrice: gasPrice,
});
```
**Parameters:**
* `response.approvalAddress`: The approval address returned in the API response.
* `approvalAmount`: The amount of tokens to approve (usually the same as `amount` in the request).
* `userAddress`: Your wallet address (must match `sender` in the request).
* `gasAmount`: The gas limit for the approval transaction.
* `gasPrice`: The gas price for the transaction.
***
### Executing the Intent
After approval, you can execute the transaction using the `data` and `to` fields from the best quote. This can be a trade or a DeFi interaction, such as adding liquidity to a pool.
#### Sample Execution Code (JavaScript with ethers.js)
```javascript
javascriptCopy code// Assume `response` is the API response object
const data = response.quotes[0]; // Selecting the best quote
if (!data) {
throw new Error("No quote data available.");
}
const txData = {
to: data.to,
data: data.data,
value: ethers.BigNumber.from(data.value),
gasLimit: ethers.BigNumber.from(Math.ceil(data.gasEstimate * 1.5)).toString(),
};
try {
const txReceipt = await signer.sendTransaction(txData);
const receipt = await txReceipt.wait();
console.log("Transaction successful:", receipt);
} catch (error) {
console.error("Transaction failed:", error);
throw error;
}
```
**Parameters:**
* `signer`: An instance of an ethers.js Signer connected to your wallet.
* `data.to`: The address to send the transaction to.
* `data.data`: The calldata for the transaction.
* `data.value`: The amount of Ether to send (usually zero).
* `data.gasEstimate`: Estimated gas units (multiplied by 1.5 for safety).
***
### Error Handling
The API may return the following error responses:
* **400 Bad Request:** The request is malformed or missing required parameters.
* Example response:
```json
jsonCopy code{
"error": "Missing required field: amount"
}
```
* **404 Not Found:** The requested resource cannot be found.
* Example response:
```json
jsonCopy code{
"message": "Route not found"
}
```
Ensure that all required fields are included and valid in your request.
***
### Additional Resources
For more detailed information, refer to the Swagger API documentation:
* **API URL (Base Network):** `https://metasolvertest.velvetdao.xyz`
#### Endpoints
**`/best-quotes`**
* **Method:** `POST`
* **Description:** Retrieves the best quotes with transaction data from solvers and market makers for trades and DeFi interactions.
* **Required Body Parameters:**
* Same as in the Request Details section.
**`/best-amount-out`**
* **Method:** `POST`
* **Description:** Retrieves the best `amountOut` value from solvers and market makers without transaction data.
* **Required Body Parameters:**
* `amount`, `tokenIn`, `tokenOut`, `sender`, `receiver`, `chainId`
**`/swap-data`**
* **Method:** `POST`
* **Description:** Retrieves transaction data for a specific protocol.
* **Required Body Parameters:**
* `slippage`, `amount`, `tokenIn`, `tokenOut`, `sender`, `amountOut`, `protocol`, `receiver`, `chainId`
***
### Conclusion
The Intent Execution API streamlines the process of obtaining and executing the best quotes from solvers and market makers for both trading and DeFi interactions, such as entering liquidity pools. By following the steps outlined in this documentation, traders can integrate the API into their workflow to optimize trading strategies and enhance execution efficiency.
For any issues or further assistance, please refer to the Swagger API documentation or contact support.
# Building a Custom App
Velvet's infrastructure is available on a white-label basis for crypto projects, platforms, and institutional teams that want to launch branded onchain trading products.
A custom app runs under your own domain and brand while leveraging Velvet's execution engine (cross-chain spot and perps routing), AI stack, wallet infrastructure, and other systems - eliminating the time and cost of building core trading infrastructure from scratch.
To discuss a white-label deployment please [contact the team](mailto:info@velvet.capital).\
# Why Velvet
Velvet combines intent-based execution, account abstraction, and an AI framework into a single onchain trading stack.
### Intent-Execution Routing
Velvet's intent-based architecture routes orders across aggregators, solvers, market makers, AMMs, and other venues to deliver best available quote among integrated sources with MEV protection.
### Multi-Chain by Default
Trade across Solana, Base, BNB Chain, Robinhood, Ethereum, Hyperliquid, and more from a single interface, including cross-chain swaps that complete in seconds. Perpetual futures are integrated through Hyperliquid and builder-deployed HIP-3 markets.
### Social & Wallet Intelligence
Velvet indexes 13M+ smart wallets and KOL accounts, linking onchain activity to social identity. Traders can track what top wallets are accumulating, follow KOLs, and act on early signals.
### AI Built Into the Workflow
Velvet Unicorn, the intelligence layer of the platform, assists with token research, risk and momentum analysis, and trade preparation and execution through natural language. All AI-assisted actions are initiated and controlled by the user.
### Self-Custody Throughout
Trades execute directly from the user's wallet. The Company does not take custody of user assets. Embedded wallets are secured through Turnkey infrastructure, and external wallets can be connected.
### Open Infrastructure
An API layer exposes Velvet's execution and intelligence stack for automation and integration, and the same infrastructure is available on a white-label basis for teams launching their own branded apps.
# Fees
## Platform Fees
Velvet applies different fees depending on the trading method used.
For onchain trading: Classic Trade fee is 0.5%. Turbo Buy and Sell, Advanced Orders (including TP/SL, DCA, and Wallet Buys / Sells) - 1%.
For perpetuals: 0.1%.
Trading fees are reduced according to your cashback tier, determined by veVELVET balance and 30-day trading volume; at the highest tier, fee reductions can reach up to 100% of trading fees paid. Cashback is a rebate of fees paid under current promotional program terms, and is not income, yield, or a return on holding any token.
## Portfolio Management Fees
Vault fees are set by and paid to independent vault creators, not to Velvet. Vault managers can set up the following types of fees for their vaults:
1. **Management Fee:**
* Continuous constant fee defined as an annualized % of the total value locked (TVL)
* Calculated & charged during deposits / withdrawals or when the vault manager calls the function to charge the fees
2. **Entry / Exit Fees:**
* Fixed fee defined as a % of deposit / withdrawal
* Charged every time the user deposits or withdraws
3. **Performance Fee:**
* Defined as a % of the difference between the asset's current price and its high watermark
* Calculated & charged during deposits / withdrawals or when the vault manager calls the function to charge the fees
* Important: performance fees can be charged only on realized gains, i.e., vault managers must "take profit" by converting their portfolio into WETH, Stablecoins or other major assets
All fees are charged in a form of vault tokens (index tokens) that are being minted according to the calculations.
# Airdrop
The Velvet Airdrop distributes $VELVET to platform users every epoch. It is designed to reward the traders, stakers, and community members who actively use the platform and help it grow.
You can track your rank, gems, and rewards on the [Rewards page](https://x.velvet.capital/rewards).
***
### Epochs
$VELVET is distributed in epochs. At the end of each epoch, the Gem leaderboard is snapshotted and the epoch’s allocation is distributed based on your rank.
**Current epoch:** ends August 10, 2026, with a distribution of **2,710,049 $VELVET**.
### Allocation
Your share of this epoch’s distribution is determined by your position on the [Gem leaderboard](https://x.velvet.capital/rewards):
#### Top Rank Allocations
Rank
Allocation
Rank 1
5%
Rank 2
4.5%
Rank 3
4%
Rank 4
3.5%
Rank 5
3%
Rank 6
2.5%
Rank 7
2%
Rank 8
1.75%
Rank 9
1.5%
Rank 10
1.25%
#### Mid Tier Ranks
* **Ranks 11 to 50:** Sliding scale from **1.24% to 0.355%**
* **Ranks 51 to 425:** Sliding scale from **0.35% to 0.002%**
#### **Long Tail**
* **Rank 426 and above** still receive a small share of the remaining rewards, ensuring all active users continue to benefit.
The detailed allocation table for the top 200 ranks is available on the Rewards page.
***
### Earning Gems
Gems are earned through platform activity:
| Activity | Gems |
| ------------------ | ---------------------------------------------- |
| VELVET staking | Based on your veVELVET amount |
| Spot trading | Based on your onchain trading volume on Velvet |
| Perpetuals trading | Based on your perp trading volume on Velvet |
| Referrals | Based on the trading volume of your referrals |
You can stake VELVET on the [Staking tab](https://x.velvet.capital/rewards?tab=staking) of the Rewards page.
***
### Gem Multipliers
Two multipliers boost your gem earning rate:
1. **Daily Challenge** — an additional multiplier for maintaining a daily streak, starting at 5% on Day 1 and growing to 150% on Day 30 and beyond
2. **Trading Volume Rank** — an additional multiplier based on your trading volume, from 5% at $1k up to 350% at $2m, plus an additional 100% for every $1m of volume after that
### Cashback
Trading fee cashback is determined by two tiers, which you can manage on the [Cashback tab](https://x.velvet.capital/rewards?tab=cashback):
1. **Staking** — from 5% at 100 veVELVET up to 50% at 1,000,000 veVELVET
2. **Volume** — calculated as 1x spot volume + 0.2x perpetuals volume, from 2.5% at $1k up to 50% at $10m
The two tiers stack, for a maximum combined cashback of 100%.
***
### Referral Commission
In addition to referral gems, you receive **50% of the fees** paid by every wallet you refer.
***
### Founders Club NFT
Holders of the **Velvet Founders Club NFT** receive a **2x boost** on all gem earning.
***
Epoch size, gem rates, multipliers, and other program parameters may be adjusted between epochs. Any changes will be announced before taking effect.
# Governance
### Overview
This page describes how the Velvet protocol is governed today, how governance is intended to evolve. Velvet follows a progressive decentralization model: governance authority is being transferred from the core team to $VELVET tokenholders in stages, as the protocol, its community, and the supporting legal and technical infrastructure mature.
### Velvet Foundation
Velvet Foundation is the intended governance body of the protocol. $VELVET, staked as veVELVET, is designed to serve as the Foundation governance mechanism: voting power corresponds to veVELVET balance, which reflects both the amount of $VELVET staked and the duration of the lock (see Tokenomics).
Once live, veVELVET voting is expected to cover major protocol decisions, including new integrations, treasury allocation, and protocol parameters. Any future proposal affecting the allocation of protocol fees would likewise be subject to the Foundation governance process and legal review before implementation.
### Current State and Path to Decentralization
Onchain governance voting is not yet live. This description will be updated as governance milestones are reached.
Governance authority will move to veVELVET holders progressively. The intended sequence is: (i) activation of onchain voting for defined proposal categories; (ii) expansion of the categories under DAO control as participation and infrastructure mature; and (iii) DAO oversight of treasury and fee-allocation decisions. Timing depends on technical readiness, community participation, and legal review.
### The Team
Velvet was founded in 2022 by a team of crypto-natives active in the space since 2016, with backgrounds spanning traditional finance, management consulting, and blockchain infrastructure.
The founding team's experience includes strategy consulting at Boston Consulting Group advising Sovereign Wealth Funds, Family Offices, Private Equity Funds, Investment Banks & other institutional clients; launching digital investment and banking platforms in traditional finance; running one of the first Web3 incubators & VCs; holding one of the first individual grants at the Ethereum Foundation; contributing to the core Solidity repository; blockchain engineering at the top Web3 protocols; full-stack engineering with Red Hat, Google & other companies, alongside 30+ hackathon wins. The team brings 10+ years of development experience in open finance and Web3 and has built infrastructure for $1B+ crypto projects.
Velvet is backed by YZi Labs (formerly Binance Labs), Selini Capital, Gate Labs, Cointelegraph Ventures, Blockchain Founders Fund, Mucker Capital, Mindfulness Capital, NxGen, Gains Associates, PAKA Fund, Funfair Ventures, Aweh Ventures, Rarestone Capital, and other institutional investors.
# Tokenomics
### 1. Design Principles
1. Align incentives among users, holders, long-term backers and the Foundation
2. Make $VELVET the coordination layer of the Velvet ecosystem
3. Bootstrap initial usage through rewards that decline over time
***
### 2. Velvet Token Stack at a Glance
$VELVET is the main token of the Velvet ecosystem, which unlocks utility once staked as veVELVET.
veVELVET is the vote-escrowed version of $VELVET. Users can stake their $VELVET tokens to get veVELVET. The longer the lock, the higher the amount of veVELVET received. To encourage continuous locking and sustained participation from stakeholders, the veVELVET balance declines over time until it reaches zero at the conclusion of the initial locking period. It can be increased by extending or restarting the locking period.
Live today, veVELVET provides:
1. $VELVET emissions rewards from the Airdrop & Staking Rewards allocation fixed at TGE, calculated based on the Gems balance (a function of the staked amount and user activity on Velvet)
2. Trading fee discounts according to cashback tiers
3. Increased Gem reward rate according to tiers
In Development (not yet live):
veVELVET is designed to serve as the voting mechanism of Velvet DAO governance. Onchain governance voting is not yet live; once activated, veVELVET holders will vote on major DAO decisions (e.g., new integrations, treasury allocation, protocol parameters).
Future uses of protocol fees may be proposed through the applicable governance process, subject to technical, economic and legal review.
***
### 3. veVELVET: Locking, Boost & Governance
Lock Range:
* 1 week → 200 weeks, 200 weeks = max-ve (1 VELVET → 1 veVELVET).
Linear Decay:
* veVELVET balance decreases towards lock expiry; UI can auto-relock if user opts in.
$VELVET staking rewards (live):
* veVELVET stakers receive $VELVET rewards from the Airdrop & Staking Rewards allocation fixed at TGE
* Rewards are calculated based on the Gems balance (a function of the staked amount and activity on Velvet)
***
### 4. Protocol Fees and the DAO
The protocol generates fees from platform activity (see the Fees page). Today, protocol fees accrue to the Treasury and fund operations, development, marketing, audits, and ecosystem growth. Any future change to how protocol fees are allocated — including any proposal to direct a portion toward staking rewards — would be subject to the Velvet DAO governance process (once governance is live) and legal review. No fee-allocation change has been finalized, scheduled, or committed.
***
### 5. Utility & Incentive Programs
* Trading Fee Discounts: Based on veVELVET balance and 30-day trading volume, users receive trading fee discounts (cashback tiers) when using the platform
* Launchpad Daily Runner Drops: A percentage of every new token supply is reserved based on the amount of Gems (a function of staked amount & activity on Velvet)
* Designated Trading Pair: VELVET is the designated trading pair for tokens created on Velvet's launchpad and structured products
* AI Access: veVELVET provides access to the Velvet AI copilot & future AI models
Additional incentive programs may be proposed over time; any program involving the allocation of protocol revenue would follow the governance and review process described in Section 4.
***
### 6. Launch Allocation & Unlock Schedule
### **6.1 Token Allocation**
### **6.2 Details & Vesting.**
### Early Backers
\~15% of the supply is reserved to be distributed to the earliest backers (with a part of it already allocated to YZi Labs (formerly known as Binance Labs), Selini Capital, Cointelegraph Ventures, Blockchain Founders Fund, PAKA funds, Mucker Capital, FunFair Ventures and other initial investors) to bring top-tier partners supporting the launch and scaling of Velvet DAO.
### Community Round
\~0.53% of the supply is reserved for the Tachyon community via Echo community round
### Binance Wallet IDO
2% of the supply is reserved for a Binance Wallet IDO.
### Reserved for Future Investments
\~4.5% of supply is reserved for future investments.
### Wallet Marketing
0.2% supply is reserved for a marketing campaign among top Web3 wallets.
### Foundation Treasury
\~18% of the supply is reserved for the DAO Treasury, which will be managed by the community through a decentralized autonomous organization (DAO). The tokens in the treasury will be used to fund any operating expenses of the DAO, including future development, security audits, internal growth initiatives, legal support and more.
### Ecosystem & Community
\~17.5% of the supply is reserved for an ecosystem fund, which will be used to support and incentivize developers, partners, and projects that contribute to the Velvet DAO ecosystem. This fund will be managed by the DAO community through a transparent grant process.
### The Growth Fund
5% of the supply is reserved to incentivize contributions towards ecosystem growth. One of the main initiatives is the Referral program which will heavily reward people for bringing new users to the platform.
### Team & Advisors
20% of the supply is reserved for the team to engage them in the long term success of Velvet DAO.
### Liquidity Provision
5% of the supply is reserved for liquidity provision, with a majority of it to be used to provide liquidity for $VELVET on decentralized exchanges & an allocation for market making on CEXes. This will ensure that there is enough liquidity for users to easily trade the token.
### Airdrop & Staking Rewards
5% of the supply is reserved for the initial airdrop & staking rewards for veVELVET holders to bootstrap initial decentralization and incentivize stakeholders to lock their tokens. By the time the initial 5% of rewards are distributed the Velvet DAO will be sufficiently decentralized to make further decisions regarding staking rewards and allocate an additional amount from the ecosystem fund or treasury if necessary.
### Reserved for Future Listings & Related Marketing
\~7% of the supply is reserved for listing expenses such as listing fees, launch campaigns, airdrops & other related expenses at TGE & beyond.
### **6.3 Emission Schedule**
# For Developers
This section describes the main technical elements required for smart contract integration, if you have any specific questions please don't hesitate to contact us.
### Portfolio Data
#### getTokens
Returns the current list of tokens in the vault.
**Function Signature:** getTokens() external view returns (address\[] memory)
**Returns:**
* An array of addresses representing the tokens in the vault.
**Usage:**
This function provides a list of all tokens currently held in the vault, allowing users to get an overview of the vault's composition. By converting the token balances to USD, the total value of the vault can be calculated. Dividing this total value by the total supply of portfolio tokens results in the price of each portfolio token. Additionally, the weights can be identified by knowing the USD values of each token or having a common value for each token.
#### totalSupply
Returns the total supply of the portfolio tokens.
**Function Signature:** totalSupply() external view returns (uint256)
**Returns:**
* A uint256 representing the total supply of the portfolio tokens.
**Usage:** This function provides the total supply of the portfolio tokens. It is useful for understanding the overall amount of tokens issued by the portfolio.
### Deposit
#### multiTokenDeposit
Allows the sender to deposit multiple tokens into the fund.
**Function Signature:** multiTokenDeposit(uint256\[] calldata depositAmounts, uint256 \_minMintAmount, IAllowanceTransfer.PermitBatch calldata \_permit, bytes calldata \_signature) external
**Parameters:**
* depositAmounts: Array of amounts for each token to deposit.
* \_minMintAmount: Minimum amount of portfolio tokens expected to mint. This is used to protect against slippage.
* \_permit: Permit batch for tokens. This includes details for each token, spender address, and the signature deadline.
* \_signature: Signature for the permit batch.
#### multiTokenDepositFor
Allows a specified depositor to deposit multiple tokens into the fund.
**Function Signature:** multiTokenDepositFor(address \_depositFor, uint256\[] calldata depositAmounts, uint256 \_minMintAmount) external
**Parameters**:
* \_depositFor: Address of the user for whom the deposit is being made.
* depositAmounts: Array of amounts for each token to deposit.
* \_minMintAmount: Minimum amount of portfolio tokens expected to mint. This is used to protect against slippage.
### Withdraw
#### multiTokenWithdrawalFor
Allows an approved user to withdraw portfolio tokens on behalf of another user.
**Function Signature:** multiTokenWithdrawalFor(address \_withdrawFor, address \_tokenReceiver, uint256 \_portfolioTokenAmount) external
**Parameters:**
* \_withdrawFor: Address of the user on whose behalf the withdrawal is being made.
* \_tokenReceiver: Address where the withdrawn portfolio tokens will be sent.
* \_portfolioTokenAmount: Amount of portfolio tokens to withdraw.
**Usage:** This function allows an approved user to withdraw a specified amount of portfolio tokens on behalf of another user. The portfolio tokens are sent to the specified \_tokenReceiver address.
#### multiTokenWithdrawal
Allows users to withdraw their deposit from the fund.
**Function Signature:** multiTokenWithdrawal(uint256 \_portfolioTokenAmount) external
**Parameters:**
* \_portfolioTokenAmount: Amount of portfolio tokens to withdraw.
**Usage:** This function allows users to withdraw their deposits from the fund by burning the specified amount of portfolio tokens.
#### emergencyWithdrawal
Allows users to perform an emergency withdrawal.
**Function Signature:** emergencyWithdrawal(uint256 \_portfolioTokenAmount, address\[] memory \_exemptionTokens) external
**Parameters:**
* \_portfolioTokenAmount: Amount of portfolio tokens to withdraw.
* \_exemptionTokens: Array of token addresses that are exempt from withdrawal restrictions.
**Usage:** This function allows users to perform an emergency withdrawal of their funds. The \_exemptionTokens parameter lets users specify tokens they are willing to lose due to potential transfer issues. These tokens are handled within a try-catch block; if a transfer restriction or any other issue arises with a specified \_exemptionToken, the error is caught, and the withdrawal process continues without withdrawing that underlying portfolio token.
#### emergencyWithdrawalFor
Allows an authorized user to perform an emergency withdrawal on behalf of another user.
**Function Signature:** emergencyWithdrawalFor(address \_withdrawFor, address \_tokenReceiver, uint256 \_portfolioTokenAmount, address\[] memory \_exemptionTokens) external
**Parameters:**
* \_withdrawFor: Address of the user on whose behalf the emergency withdrawal is being made.
* \_tokenReceiver: Address where the withdrawn tokens will be sent.
* \_portfolioTokenAmount: Amount of portfolio tokens to withdraw.
* \_exemptionTokens: Array of token addresses that are exempt from withdrawal restrictions.
**Usage:** This function allows users to perform an emergency withdrawal on behalf of another user. The \_exemptionTokens parameter lets users specify tokens they are willing to lose due to potential transfer issues. These tokens are handled within a try-catch block; if a transfer restriction or any other issue arises with a specified \_exemptionToken, the error is caught, and the withdrawal process continues without withdrawing that underlying portfolio token.
### Claim Removed Portfolio Tokens
#### claimRemovedTokens
Allows users to claim their share of removed portfolio tokens.
**Function Signature:** claimRemovedTokens(address user, uint256 startId, uint256 endId) external
**Parameters:**
* user: Address of the user claiming the tokens.
* startId: The starting ID from which tokens are being claimed.
* endId: The ending ID up to which tokens are being claimed.
**Usage:** This function allows users to claim their share of removed tokens within a specified range, from startId to endId. It is useful for claiming multiple tokens in one transaction.
#### claimTokenAtId
Claims a removed token for a given user at a specific ID.
**Function Signature:** claimTokenAtId(address user, uint256 id) external
**Parameters:**
* user: Address of the user claiming the token.
* id: The ID of the token being claimed.
**Usage:** This function allows a user to claim a removed token at a specific ID. It is useful for claiming a single token without needing to specify a range.
#### getDataAtId
Retrieves the validity and balance of a user's interaction at a given ID.
**Function Signature:** getDataAtId(address user, uint256 id) external view returns (bool, uint256)
**Parameters:**
* user: Address of the user.
* id: The ID for which data is being retrieved.
**Returns:**
* bool: A boolean indicating the validity of the interaction at the given ID.
* uint256: The balance of the user at the given ID.
**Usage:** This function retrieves the validity and balance of a user's interaction at a specific ID. It is useful for verifying the status and amount of tokens before performing a claim.
# Portfolio Management API
#### Overview
The Velvet Portfolio Management API enables you to manage and rebalance tokenized portfolios (vaults) programmatically. With this API, you can:
* Retrieve and inspect all portfolios (vaults) created by a given owner.
* Rebalance portfolios by selling one token and buying another.
* Execute trades using on-chain calls.
* Deposit and withdraw tokens from portfolios.
* Obtain helper information, such as the number of portfolio tokens a user holds.
This guide will walk you through key endpoints and illustrate how to integrate the provided data and call parameters into your applications.
***
#### Prerequisites
* A wallet with a private key to sign blockchain transactions.
* A JSON-RPC provider URL for your target chain (for instance, Base chain with chainId = 8453).
* Familiarity with Ethereum-compatible contracts, tokens, and basic web3 concepts.
***
#### Trade Flow Overview
To execute a trade withing a Velvet portfolio (vault), follow these steps:
1. **Fetch All Created Vaults**: Retrieve all portfolios (vaults) associated with a specific owner.
2. **Use the Rebalance API Endpoint**: Generate the necessary call data and parameters for the intended trade.
3. **Execute the Trade On-Chain**: Use the parameters from the Rebalance API to call the vault’s rebalance contract function.
***
#### Fetch All Created Vaults
**Endpoint**: `GET https://api.velvet.capital/api/v3/portfolio/owner/?chain=base`
**Description**: Retrieves all vaults created by a specified owner on the Velvet V3 platform.
**URL Parameters**:
* `OWNER_WALLET_ADDRESS` (string): The Ethereum address of the owner.
**Response**:
Copy
```
jsonCopy code{
"data": [
{
"portfolioId": "string",
"portfolio": "string",
"name": "string",
"symbol": "string",
"public": true,
"initialized": true,
"confirmed": true,
"tokenExclusionManager": "string",
"rebalancing": "string", // ← Use this address in next steps
"owner": "string",
"assetManagementConfig": "string",
"accessController": "string",
"feeModule": "string",
"vaultAddress": "string",
"gnosisModule": "string",
"whitelistedUsers": [],
"whitelistedTokens": [],
"whitelistAccessGrantedUsers": [],
"assetManagerAccessGrantedUsers": [],
"chainID": 8453,
"chainName": "base",
"txnHash": "string",
"createdAt": "Date",
"updatedAt": "Date",
"creatorName": "string",
"description": "string",
"avatar": "string"
}
]
}
```
**Usage**: From the response, note the `rebalancing` address, which will be needed to prepare the trade in the next step.
***
#### Rebalance API Endpoint
**Endpoint**: `POST https://eventsapi.velvetdao.xyz/api/v3/rebalance`
**Description**: Generates the necessary parameters (call data, handler address, etc.) to execute a trade within a portfolio’s rebalance contract.
**Request Body**:
Copy
```
jsonCopy code{
"rebalanceAddress": "string",
"sellToken": "string",
"buyToken": "string",
"sellAmount": "string",
"slippage": "string",
"remainingTokens": ["string"],
"owner": "string"
}
```
**Parameters**:
* `rebalanceAddress` (string, required): The rebalance contract address retrieved from the "Fetch All Created Vaults" response.
* `sellToken` (string, required): The token address you want to sell.
* `buyToken` (string, required): The token address you want to buy.
* `sellAmount` (string, required): The amount of `sellToken` to sell (in smallest unit, e.g., if USDC is 6 decimals, `1 USDC` = `1000000`).
* `slippage` (string, required): Allowed slippage in basis points. For example, `"100"` means 1%.
* `remainingTokens` (array, required): The list of tokens that will remain in the vault after the trade.
* `owner` (string, required): The vault owner’s Ethereum address.
**Response**:
Copy
```
jsonCopy code{
"newTokens": ["string"],
"sellTokens": ["string"],
"sellAmounts": ["string"],
"handler": "string",
"callData": "string",
"estimateGas": "string",
"gasPrice": "string"
}
```
**Note**: Use the returned data (`newTokens`, `sellTokens`, `sellAmounts`, `handler`, and `callData`) to execute the trade in the next step.
***
#### Executing the Trade On-Chain
After obtaining the necessary parameters from the Rebalance API, you can execute the trade by interacting directly with the rebalance contract on-chain.
**Prerequisite**: Install Ethers.js:
Copy
```
bashCopy codenpm install ethers@5.5.4
```
**Example Code**:
Copy
```
javascriptCopy codeimport { ethers } from 'ethers'
const provider = new ethers.providers.JsonRpcProvider('')
const privateKey = ''
const wallet = new ethers.Wallet(privateKey, provider)
const RebalanceABI = [
{
inputs: [
{
components: [
{ internalType: 'address[]', name: '_newTokens', type: 'address[]' },
{ internalType: 'address[]', name: '_sellTokens', type: 'address[]' },
{ internalType: 'uint256[]', name: '_sellAmounts', type: 'uint256[]' },
{ internalType: 'address', name: '_handler', type: 'address' },
{ internalType: 'bytes', name: '_callData', type: 'bytes' }
],
internalType: 'struct FunctionParameters.RebalanceIntent',
name: 'rebalanceData',
type: 'tuple'
}
],
name: 'updateTokens',
outputs: [],
stateMutability: 'nonpayable',
type: 'function'
}
]
const RebalanceInstance = new ethers.Contract(
'VAULT_REBALANCING_ADDRESS',
RebalanceABI,
wallet
)
async function executeRebalance(newTokens, sellTokens, sellAmounts, handler, callData, estimateGas, gasPrice) {
try {
console.log('Executing Trade...')
const tx = await RebalanceInstance.updateTokens(
{
_newTokens: newTokens,
_sellTokens: sellTokens,
_sellAmounts: sellAmounts,
_handler: handler,
_callData: callData
},
{
gasLimit: ethers.BigNumber.from(estimateGas).add('1000000'),
gasPrice: gasPrice
}
)
console.log('Transaction successful:', tx)
} catch (error) {
console.error('Transaction failed:', error)
}
}
```
***
#### Rebalance Transaction API
**Endpoint**: `POST https://eventsapi.velvetdao.xyz/api/v3/rebalance/txn`
**Description**: Initiates a rebalance transaction directly. Useful when you already know the parameters required to perform the rebalance.
**Request Body**:
Copy
```
jsonCopy code{
"rebalanceAddress": "0x19bc26a8e42727a2567d244cca344ceddd0493ae",
"sellToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"buyToken": "0xb6fe221fe9eef5aba221c348ba20a1bf5e73624c",
"sellAmount": "883373",
"slippage": "100",
"remainingTokens": [
"0xb6fe221fe9eef5aba221c348ba20a1bf5e73624c",
"0xc1CBa3fCea344f92D9239c08C0568f6F2F0ee452"
],
"owner": "0x86F91b660a5432CE4654D84B3AbAD38A6645425e"
}
```
**Parameters**:
* Similar to the Rebalance API Endpoint (above), but returns direct transaction data for immediate execution.
***
#### Portfolio Deposit API
**Endpoint**: `POST https://eventsapi.velvetdao.xyz/api/v3/portfolio/deposit`
**Description**: Deposits a specified amount of tokens into a given portfolio.
**Request Body**:
Copy
```
jsonCopy code{
"portfolio": "0x444ef5b66f3dc7f3d36fe607f84fcb2f3a666902",
"depositAmount": "1000000",
"depositToken": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
"user": "0x3C96e2Fc58332746fbBAB5eC44f01572F99033ed",
"depositType": "batch",
"tokenType": "erc20"
}
```
**Parameters**:
* `portfolio`: The portfolio contract address.
* `depositAmount`: The amount to deposit (in token’s smallest unit).
* `depositToken`: The token’s contract address being deposited.
* `user`: The depositor’s Ethereum address.
* `depositType`: The deposit mode (e.g., `batch`).
* `tokenType`: The type of token (e.g., `erc20`).
**Response**: Returns transaction data (`to`, `data`, `gasLimit`, `gasPrice`) needed to broadcast the transaction.
**Example Code**: After approval, send the returned transaction data via `wallet.sendTransaction(tx)`.
***
#### Portfolio Withdraw API
**Endpoint**: `POST https://eventsapi.velvetdao.xyz/api/v3/portfolio/withdraw`
**Description**: Initiates a withdrawal from a specified portfolio.
**Request Body**:
Copy
```
jsonCopy code{
"portfolio": "0xc4dc922c90d44d07ea5d1aa8c08253ebc17e42c2",
"withdrawAmount": "8999999999989636786",
"withdrawToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"user": "0x86F91b660a5432CE4654D84B3AbAD38A6645425e",
"withdrawType": "batch",
"tokenType": "erc20"
}
```
**Parameters**:
* `portfolio`: The portfolio address.
* `withdrawAmount`: The withdrawal amount (in smallest unit).
* `withdrawToken`: The token address to withdraw.
* `user`: The user’s Ethereum address initiating the withdrawal.
* `withdrawType`: The withdrawal mode (e.g. `batch`).
* `tokenType`: The type of token (e.g., `erc20`).
**Response**: Returns transaction data needed to finalize the withdrawal transaction on-chain.
**Edge Case**: If the portfolio contains only one token and the user wishes to withdraw that same token, use the `multiTokenWithdrawal`function from the portfolio contract’s ABI.
***
#### Helper Functions
**Get Portfolio Token Amount**
**Function**: `getPortfolioTokenAmount(portfolioAddress, account, chainId=8453)`
**Description**: Returns the number of portfolio tokens a user holds.
**Example**:
Copy
```
javascriptCopy codeexport const getPortfolioTokenAmount = async (portfolioAddress, account, chainId = 8453) => {
try {
const web3 = getWeb3Provider(chainId);
const ContractInstance = new web3.eth.Contract(
portfolio_abi,
portfolioAddress
);
const contractData = await ContractInstance.methods.balanceOf(account).call();
return web3.utils.fromWei(contractData, 'ether');
} catch (error) {
console.log(error, 'error');
}
};
```
***
#### Conclusion
With the endpoints and code samples provided, you should be able to:
* Discover and manage all your Velvet vaults.
* Programmatically prepare and execute trades through the Rebalance interface.
* Deposit and withdraw tokens from portfolios.
* Monitor and query token amounts within portfolios.
For a seamless integration, ensure you handle proper token approvals and confirm transactions on-chain. By following these guidelines and examples, you can fully leverage the Velvet Portfolio Management API.
Happy coding!
# Smart Contract Documentation
This document contains documentation for the latest Velvet smart contracts, please don't hesitate to reach out for integration support.
### Introduction
Velvet v4 protocol is a DeFi protocol enabling creation, management, and interaction with onchain portfolios. It allows portfolio managers to construct & manage bespoke portfolios across a diverse range of tokens & protocols and facilitate deposit/withdrawal process.
**Key Features:**
* **Portfolio Creation:** Portfolio managers can deploy both custodial and non-custodial portfolios setting up parameters like management fees, performance fees, entry and exit fees, token whitelists, initial token supply, and transferability options. Safe (fka Gnosis Safe) standard is used for portfolio creation.
* **Deposit and Withdrawal:** Depositors can supply multiple tokens into portfolios via single or batched transactions, with support for gasless approvals through Permit2. Withdrawals are flexible, allowing depositors to receive specific underlying assets or to repay associated debts, offering granular control over their portfolio positions.
* **Rebalancing:** Managers have the tools to update the portfolio's asset composition and adjust token weights dynamically. This enables them to rebalance portfolios in response to market movements, maintain desired asset allocations, and optimize for performance or risk management. Rebalancing includes trading and allocation into DeFi pools generating additional yield (routed using Velvet solver network).
* **External Position Management:** The protocol is also directly integrated with DeFi primitives such as Uniswap V3, Thena or similar. Portfolio managers can create and manage liquidity positions, adjust price ranges, and reinvest earned fees, enabling portfolios to participate in yield farming, liquidity provision, and other advanced DeFi strategies.
* **Debt Management:** Portfolio managers can engage in borrowing and lending activities, utilizing tokens as collateral to borrow assets from lending protocols. They can manage collateralization ratios, perform flash loans for efficient debt repayment, and adjust portfolio leverage, allowing for sophisticated debt strategies within the portfolio.
* **Portfolio Management Configuration:** Managers can propose and adjust various fees associated with the portfolio, including management, performance, entry, and exit fees. The protocol incorporates governance mechanisms such as time-locked proposals and the ability to cancel proposals, ensuring transparent and fair fee management.
* **Treasury and Whitelist Management:** The platform allows updating of treasury addresses for fee accrual and supports robust user management via whitelisting. Portfolio managers can control depositor access to their portfolios, manage permissions, and tailor depositor communities.
* **Token Exclusion Handling:** In scenarios where certain tokens need to be removed from a portfolio—such as due to liquidity issues or protocol changes—the protocol provides mechanisms for portfolio managers to exclude tokens and for depositors to claim their proportionate share of them.
Velvet v4 supports advanced portfolio management, diverse DeFi strategies, and seamless interactions with other DeFi protocols. See detailed developer documentation below.
### Velvet Core
The Velvet Core contracts facilitate the creation of new portfolios and provide core functionalities for portfolio management.
#### Create New Portfolio
**createPortfolioNonCustodial**
Creates a new non-custodial portfolio with specified parameters. This type of portfolio is managed directly by the asset manager without the use of a custodial wallet.
Copy
```
function createPortfolioNonCustodial(FunctionParameters.PortfolioCreationInitData memory initData) external;
```
**Parameters:**
* `initData`: A struct containing initialization data for the portfolio.
***
**createPortfolioCustodial**
Creates a new custodial portfolio managed by a Gnosis Safe, allowing for multi-signature control and enhanced security.
Copy
```
function createPortfolioCustodial(
FunctionParameters.PortfolioCreationInitData memory initData,
address[] memory _owners,
uint256 _threshold
) external;
```
**Parameters:**
* `initData`: Initialization data for the portfolio.
* `_owners`: Array of addresses that will own the Gnosis Safe.
* `_threshold`: The minimum number of owner signatures required for transactions.
***
**PortfolioCreationInitData Struct**
Defines the initial configuration parameters for creating a new portfolio.
Copy
```
struct PortfolioCreationInitData {
address _assetManagerTreasury;
address[] _whitelistedTokens;
uint256 _managementFee;
uint256 _performanceFee;
uint256 _entryFee;
uint256 _exitFee;
uint256 _initialPortfolioAmount;
uint256 _minPortfolioTokenHoldingAmount;
bool _public;
bool _transferable;
bool _transferableToPublic;
bool _whitelistTokens;
bool _externalPositionManagementWhitelisted;
string _name;
string _symbol;
}
```
**Fields:**
* `_assetManagerTreasury`: Address for fee accumulation.
* `_whitelistedTokens`: Tokens allowed in the portfolio.
* `_managementFee`: Annual management fee in basis points.
* `_performanceFee`: Fee on profits in basis points.
* `_entryFee`: One-time entry fee in basis points.
* `_exitFee`: Exit fee in basis points.
* `_initialPortfolioAmount`: Initial supply of portfolio tokens (>= 1e14).
* `_minPortfolioTokenHoldingAmount`: Minimum holding amount (>= 1e14).
* `_public`: Indicates if the fund is open to the public.
* `_transferable`: If tokens are transferable.
* `_transferableToPublic`: If tokens can be transferred to non-whitelisted addresses.
* `_whitelistTokens`: Restricts the fund to whitelisted tokens.
* `_externalPositionManagementWhitelisted`: Allows external position management.
* `_name`: Name of the portfolio token.
* `_symbol`: Symbol of the portfolio token.
***
**Event Emission on Portfolio Creation**
An event is emitted when a new portfolio is created, providing details about the portfolio.
Copy
```
event PortfolioInfo(
PortfoliolInfo portfolioData,
uint256 indexed portfolioId,
string _name,
string _symbol,
address indexed _owner,
address indexed _accessController,
bool isPublicPortfolio
);
```
**Event Parameters:**
* `portfolioData`: Struct with portfolio-related addresses.
* `portfolioId`: Unique identifier for the portfolio.
* `_name`: Name of the portfolio token.
* `_symbol`: Symbol of the portfolio token.
* `_owner`: Address of the portfolio owner.
* `_accessController`: Access controller address.
* `isPublicPortfolio`: Indicates if the portfolio is public.
***
**PortfoliolInfo Struct**
Contains addresses of various contracts associated with the portfolio.
Copy
```
struct PortfoliolInfo {
address portfolio;
address tokenExclusionManager;
address rebalancing;
address owner;
address borrowManager;
address assetManagementConfig;
address feeModule;
address vaultAddress;
address gnosisModule;
}
```
**Fields:**
* `portfolio`: Portfolio contract address.
* `tokenExclusionManager`: Manages token exclusions.
* `rebalancing`: Rebalancing contract address.
* `owner`: Owner's address.
* `borrowManager`: Manages borrowing operations.
* `assetManagementConfig`: Asset management configuration.
* `feeModule`: Fee module address.
* `vaultAddress`: Vault contract address.
* `gnosisModule`: Gnosis Safe module address.
***
#### Initialize Tokens
**initTokens**
Initializes the vault with a set of tokens, setting up the initial assets managed by the portfolio.
Copy
```
function initToken(address[] calldata _tokens) external;
```
**Parameters:**
* `_tokens`: An array of token addresses to include in the vault.
***
### Deposit
Users can deposit tokens into the portfolio, either directly or on behalf of another user, using multi-token deposit functions.
#### multiTokenDeposit
Allows users to deposit multiple tokens into the portfolio in a single transaction. Supports gasless approvals through Permit2.
Copy
```
function multiTokenDeposit(
uint256[] calldata depositAmounts,
uint256 _minMintAmount,
IAllowanceTransfer.PermitBatch calldata _permit,
bytes calldata _signature
) external;
```
**Parameters:**
* `depositAmounts`: Amounts for each token being deposited.
* `_minMintAmount`: Minimum portfolio tokens expected to receive.
* `_permit`: Batch permit data for token allowance.
* `_signature`: Signature for the permit batch.
***
**PermitBatch Struct**
Used for gasless token approvals.
Copy
```
struct PermitBatch {
PermitDetails[] details;
address spender;
uint256 sigDeadline;
}
```
**Fields:**
* `details`: Array of `PermitDetails` structs.
* `spender`: Address authorized to spend tokens.
* `sigDeadline`: Signature validity deadline.
***
#### multiTokenDepositFor
Allows depositing tokens on behalf of another user.
Copy
```
function multiTokenDepositFor(
address _depositFor,
uint256[] calldata depositAmounts,
uint256 _minMintAmount
) external;
```
**Parameters:**
* `_depositFor`: Address of the user for whom the deposit is made.
* `depositAmounts`: Amounts for each token being deposited.
* `_minMintAmount`: Minimum portfolio tokens expected to receive.
***
### DepositBatch
The `DepositBatch` contract enables users to batch multiple token swaps and deposit operations, facilitating complex deposit scenarios.
#### deposit
Allows depositing tokens after performing necessary swaps and transfers, especially when dealing with tokens not directly accepted by the portfolio.
Copy
```
function deposit(FunctionParameters.BatchHandler memory data) external;
```
**BatchHandler Struct**
Copy
```
struct BatchHandler {
uint256 _minMintAmount;
uint256 _depositAmount;
address _target;
address _depositToken;
bytes[] _callData;
}
```
**Fields:**
* `_minMintAmount`: Minimum portfolio tokens expected.
* `_depositAmount`: Amount of tokens to swap.
* `_target`: Portfolio contract address.
* `_depositToken`: Initial token address to swap from.
* `_callData`: Encoded data for swap operations.
***
#### multiTokenSwapETHAndTransfer
Performs swaps for ETH deposits and transfers tokens to the portfolio.
Copy
```
function multiTokenSwapETHAndTransfer(FunctionParameters.BatchHandler memory data) external;
```
***
### DepositBatchExternalPositions
Extends `DepositBatch` functionalities to handle deposits into portfolios with external positions like Uniswap V3 or Thena.
#### deposit
Facilitates deposits involving external positions, handling swaps and liquidity operations.
Copy
```
function deposit(
FunctionParameters.BatchHandler memory data,
FunctionParameters.ExternalPositionDepositParams memory _params
) external;
```
**ExternalPositionDepositParams Struct**
Copy
```
struct ExternalPositionDepositParams {
address[] _positionWrappers;
address[] _swapTokens;
uint256[] _positionWrapperIndex;
uint256[] _portfolioTokenIndex;
uint256[] _index0;
uint256[] _index1;
uint256[] _amount0Min;
uint256[] _amount1Min;
bool[] _isExternalPosition;
address[] _tokenIn;
address[] _tokenOut;
uint256[] _amountIn;
}
```
**Fields:**
* `_positionWrappers`: External position wrapper addresses.
* `_swapTokens`: Tokens involved in swaps or liquidity.
* `_positionWrapperIndex`: Indices linking wrappers to portfolio tokens.
* `_portfolioTokenIndex`: Indices for tokens in the portfolio.
* `_index0`, `_index1`: Indices for liquidity pairs.
* `_amount0Min`, `_amount1Min`: Minimum amounts to prevent slippage.
* `_isExternalPosition`: Flags indicating external positions.
* `_tokenIn`, `_tokenOut`: Tokens for swap operations.
* `_amountIn`: Amounts for swaps.
***
### Withdrawal
Users can withdraw portfolio tokens, receiving underlying assets or swapping them into desired tokens.
#### multiTokenWithdrawal
Allows withdrawing portfolio tokens and optionally repaying debts.
Copy
```
function multiTokenWithdrawal(
uint256 _portfolioTokenAmount,
FunctionParameters.withdrawRepayParams calldata repayData
) external;
```
**Parameters:**
* `_portfolioTokenAmount`: Amount of portfolio tokens to withdraw.
* `repayData`: Parameters for debt repayment during withdrawal.
***
**withdrawRepayParams Struct**
Copy
```
struct withdrawRepayParams {
address _factory;
address _token0;
address _token1;
address _flashLoanToken;
address _solverHandler;
uint256 _bufferUnit;
uint256[] _flashLoanAmount;
bytes[] firstSwapData;
bytes[] secondSwapData;
}
```
**Fields:**
* `_factory`: Thena factory contract address.
* `_token0`, `_token1`: Tokens involved in swaps.
* `_flashLoanToken`: Token for flash loan.
* `_solverHandler`: Contract handling swaps.
* `_bufferUnit`: Buffer for safety margins.
* `_flashLoanAmount`: Amounts for flash loans.
* `firstSwapData`, `secondSwapData`: Encoded swap data.
***
#### multiTokenWithdrawalFor
Allows approved users to withdraw on behalf of others.
Copy
```
function multiTokenWithdrawalFor(
address _withdrawFor,
address _tokenReceiver,
uint256 _portfolioTokenAmount,
FunctionParameters.withdrawRepayParams calldata repayData
) external;
```
**Parameters:**
* `_withdrawFor`: Address of the user whose tokens are withdrawn.
* `_tokenReceiver`: Recipient of withdrawn tokens.
* `_portfolioTokenAmount`: Amount to withdraw.
* `repayData`: Debt repayment parameters.
***
### WithdrawalBatch
Facilitates batch withdrawals involving swaps and complex operations.
#### withdraw
Withdraws portfolio tokens and executes swaps to obtain desired output tokens.
Copy
```
function withdraw(
address _target,
address _tokenToWithdraw,
uint256 _portfolioTokenAmount,
uint256 _expectedOutputAmount,
FunctionParameters.withdrawRepayParams calldata repayData,
bytes[] memory _callData
) external;
```
**Parameters:**
* `_target`: Portfolio contract address.
* `_tokenToWithdraw`: Token to receive after withdrawal.
* `_portfolioTokenAmount`: Amount to withdraw.
* `_expectedOutputAmount`: Minimum expected output.
* `repayData`: Debt repayment parameters.
* `_callData`: Encoded swap operations.
***
### WithdrawalBatchExternalPositions
Handles withdrawals from portfolios with external positions.
#### withdraw
Manages withdrawals involving external positions and swaps.
Copy
```
function withdraw(
address[] memory _swapTokens,
address _target,
address _tokenToWithdraw,
uint256 _portfolioTokenAmount,
bytes[] memory _callData,
FunctionParameters.withdrawRepayParams calldata repayData,
FunctionParameters.ExternalPositionWithdrawParams memory _params
) external;
```
**Parameters:**
* `_swapTokens`: Tokens involved in swaps.
* `_target`: Portfolio contract address.
* `_tokenToWithdraw`: Token to receive.
* `_portfolioTokenAmount`: Amount to withdraw.
* `_callData`: Encoded swap data.
* `repayData`: Debt repayment parameters.
* `_params`: External position withdrawal parameters.
***
**ExternalPositionWithdrawParams Struct**
Copy
```
struct ExternalPositionWithdrawParams {
address[] _positionWrappers;
uint256[] _amountsMin0;
uint256[] _amountsMin1;
address[] _tokenIn;
address[] _tokenOut;
uint256[] _amountIn;
}
```
**Fields:**
* `_positionWrappers`: External position wrappers.
* `_amountsMin0`, `_amountsMin1`: Minimum amounts to prevent slippage.
* `_tokenIn`, `_tokenOut`: Tokens for swaps.
* `_amountIn`: Amounts for swaps.
***
### Rebalancing
**Note:** Functions in this section can only be called by asset managers.
Asset managers can rebalance the portfolio by updating the token list and adjusting token weights.
#### updateTokens
Updates the portfolio's token list and adjusts weights based on provided rebalance data.
Copy
```
function updateTokens(FunctionParameters.RebalanceIntent calldata rebalanceData) external;
```
**RebalanceIntent Struct**
Copy
```
struct RebalanceIntent {
address[] _newTokens;
address[] _sellTokens;
uint256[] _sellAmounts;
address _handler;
bytes _callData;
}
```
**Fields:**
* `_newTokens`: Tokens to add to the portfolio.
* `_sellTokens`: Tokens to sell during rebalancing.
* `_sellAmounts`: Amounts of tokens to sell.
* `_handler`: Address of the handler executing swaps.
* `_callData`: Encoded data for rebalancing operations.
***
#### updateWeights
Adjusts the weights of existing tokens without changing the token list.
Copy
```
function updateWeights(
address[] calldata _sellTokens,
uint256[] calldata _sellAmounts,
address _handler,
bytes memory _callData
) external;
```
**Parameters:**
* `_sellTokens`: Tokens to sell.
* `_sellAmounts`: Amounts to sell.
* `_handler`: Swap handler address.
* `_callData`: Encoded swap data.
***
#### enableCollateralTokens
Enables specified tokens as collateral in a lending protocol.
Copy
```
function enableCollateralTokens(address[] memory _tokens, address _controller) external;
```
**Parameters:**
* `_tokens`: Tokens to enable as collateral.
* `_controller`: Lending protocol controller address.
***
#### disableCollateralTokens
Disables specified tokens as collateral.
Copy
```
function disableCollateralTokens(address[] memory _tokens, address _controller) external;
```
***
#### borrow
Executes a borrow operation using designated collateral.
Copy
```
function borrow(
address _pool,
address[] memory _tokens,
address _tokenToBorrow,
address _controller,
uint256 _amountToBorrow
) external;
```
**Parameters:**
* `_pool`: Lending pool address.
* `_tokens`: Collateral tokens.
* `_tokenToBorrow`: Token to borrow.
* `_controller`: Lending protocol controller.
* `_amountToBorrow`: Amount to borrow.
***
#### repay
Repays debt using a flash loan and rebalances the portfolio.
Copy
```
function repay(
address _controller,
FunctionParameters.RepayParams calldata repayData
) external;
```
**Parameters:**
* `_controller`: Controller managing the repayment.
* `repayData`: Parameters for the repayment process.
***
**RepayParams Struct**
Refer to the `repayData` struct in the Withdrawal section for details.
***
#### directDebtRepayment
Repays debt directly by transferring debt tokens.
Copy
```
function directDebtRepayment(
address _debtToken,
address _protocolToken,
uint256 _repayAmount
) external;
```
***
#### removePortfolioToken
Removes a token from the portfolio.
Copy
```
function removePortfolioToken(address _token) external;
```
***
#### removePortfolioTokenPartially
Removes a portion of a token from the portfolio.
Copy
```
function removePortfolioTokenPartially(address _token, uint256 _percentage) external;
```
***
#### removeNonPortfolioToken
Removes a non-portfolio token.
Copy
```
function removeNonPortfolioToken(address _token) external;
```
***
#### removeNonPortfolioTokenPartially
Removes a portion of a non-portfolio token.
Copy
```
function removeNonPortfolioTokenPartially(address _token, uint256 _percentage) external;
```
***
### Token Exclusion Manager
Manages the exclusion and removal of tokens from the portfolio due to reasons like lack of liquidity.
#### claimRemovedTokens
Allows users to claim their share of tokens that have been removed from the portfolio.
Copy
```
function claimRemovedTokens(address user, uint256 startId, uint256 endId) external;
```
***
#### claimTokenAtId
Claims a specific removed token by its ID.
Copy
```
function claimTokenAtId(address user, uint256 id) external;
```
***
### Position Manager
Provides functionalities to manage liquidity positions in Uniswap V3 or Thena.
**Setup:** Enable the Uniswap V3 Manager in `AssetManagementConfig`.
Copy
```
const config = await portfolio.assetManagementConfig();
assetManagementConfig = AssetManagementConfig.attach(config);
await assetManagementConfig.enableUniSwapV3Manager();
```
***
#### createNewWrapperPositionAndDeposit
Creates a new liquidity position and makes an initial deposit.
Copy
```
function createNewWrapperPositionAndDeposit(
address _dustReceiver,
address _token0,
address _token1,
string memory _name,
string memory _symbol,
WrapperFunctionParameters.PositionMintParamsThena memory params
) external;
```
**Parameters:**
* `_dustReceiver`: Address for leftover tokens.
* `_token0`, `_token1`: Tokens in the liquidity pair.
* `_name`, `_symbol`: Name and symbol for the wrapper token.
* `params`: Parameters for minting the position.
***
**PositionMintParamsThena Struct**
Copy
```
struct PositionMintParamsThena {
uint256 _amount0Desired;
uint256 _amount1Desired;
uint256 _amount0Min;
uint256 _amount1Min;
int24 _tickLower;
int24 _tickUpper;
}
```
**Fields:**
* `_amount0Desired`, `_amount1Desired`: Desired token amounts.
* `_amount0Min`, `_amount1Min`: Minimum amounts to prevent slippage.
* `_tickLower`, `_tickUpper`: Price range ticks.
***
#### initializePositionAndDeposit
Initializes an existing position and makes a deposit.
Copy
```
function initializePositionAndDeposit(
address _dustReceiver,
IPositionWrapper _positionWrapper,
WrapperFunctionParameters.InitialMintParams memory params
) external;
```
***
#### createNewWrapperPosition
Creates a new wrapper position without an initial deposit.
Copy
```
function createNewWrapperPosition(
address _token0,
address _token1,
string memory _name,
string memory _symbol,
int24 _tickLower,
int24 _tickUpper
) public;
```
***
#### increaseLiquidity
Increases liquidity in an existing position.
Copy
```
function increaseLiquidity(WrapperFunctionParameters.WrapperDepositParams memory _params) external;
```
***
**WrapperDepositParams Struct**
Copy
```
struct WrapperDepositParams {
address _dustReceiver;
IPositionWrapper _positionWrapper;
uint256 _amount0Desired;
uint256 _amount1Desired;
uint256 _amount0Min;
uint256 _amount1Min;
address _tokenIn;
address _tokenOut;
uint256 _amountIn;
}
```
***
#### decreaseLiquidity
Decreases liquidity and burns wrapper tokens.
Copy
```
function decreaseLiquidity(
IPositionWrapper _positionWrapper,
uint256 _withdrawalAmount,
uint256 _amount0Min,
uint256 _amount1Min,
address tokenIn,
address tokenOut,
uint256 amountIn
) external;
```
***
#### updateRange
Updates the price range and fee tier of an existing position.
Copy
```
function updateRange(
IPositionWrapper _positionWrapper,
address tokenIn,
address tokenOut,
uint256 amountIn,
uint256 _underlyingAmountOut0,
uint256 _underlyingAmountOut1,
int24 _tickLower,
int24 _tickUpper
) external;
```
**Note:** Asset managers need to calculate swap parameters to maintain optimal ratios during liquidity adjustments. This involves determining collected fees, desired ratios, and required swaps to align with the new price range.
### Portfolio Data
The portfolio contracts provide functions to access and manage the tokens within the vault, as well as information about the portfolio tokens themselves.
#### getTokens
Copy
```
function getTokens() external view returns (address[] memory);
```
Retrieves the current list of token addresses held in the vault.
**Returns:**
* `address[] memory`: An array containing the addresses of the tokens in the vault.
#### totalSupply
Copy
```
function totalSupply() external view returns (uint256);
```
Returns the total supply of the portfolio tokens in circulation.
**Returns:**
* `uint256`: The total number of portfolio tokens minted.
#### balanceOf
Copy
```
function balanceOf(address account) external view returns (uint256);
```
Provides the balance of portfolio tokens held by a specific user.
**Parameters:**
* `account`: The address of the user whose balance is being queried.
**Returns:**
* `uint256`: The number of portfolio tokens owned by the specified user.
***
### Asset Management Configuration
**Note:** All functions in `AssetManagementConfig` can only be called by asset managers.
The `AssetManagementConfig` contract allows asset managers to configure various aspects of the portfolio, including external positions, fees, portfolio settings, treasury management, and user whitelist management.
#### External Position Management
**enableUniSwapV3Manager**
Enables the Uniswap V3 wrapper, allowing the portfolio to interact with Uniswap V3 positions. This is essential for portfolios that include external liquidity positions.
Copy
```
function enableUniSwapV3Manager() external;
```
***
#### Fee Management
The following functions allow asset managers to propose and update management, performance, entry, and exit fees. Each fee change involves a proposal followed by a waiting period before the update can be finalized.
**proposeNewManagementFee**
Starts the process of updating the management fee by proposing a new fee. A waiting period begins during which the proposed fee can be reviewed.
Copy
```
function proposeNewManagementFee(uint256 _newManagementFee) external;
```
**Parameters:**
* `_newManagementFee`: The proposed new management fee, expressed in basis points (e.g., 100 = 1%).
**Note:** The `updateManagementFee` function can be called 28 days after the proposal. The management fee cannot exceed the `maxManagementFee` set in the protocol configuration.
**deleteProposedManagementFee**
Cancels the proposed management fee, resetting the proposal and stopping the update process.
Copy
```
function deleteProposedManagementFee() external;
```
**updateManagementFee**
Finalizes the management fee update after the waiting period has elapsed, applying the previously proposed fee.
Copy
```
function updateManagementFee() external;
```
***
**proposeNewPerformanceFee**
Proposes a new performance fee, initiating a waiting period before the fee can be updated.
Copy
```
function proposeNewPerformanceFee(uint256 _newPerformanceFee) external;
```
**Parameters:**
* `_newPerformanceFee`: The proposed new performance fee, expressed in basis points.
**deleteProposedPerformanceFee**
Cancels the proposed performance fee, resetting the proposal.
Copy
```
function deleteProposedPerformanceFee() external;
```
**updatePerformanceFee**
Updates the performance fee to the previously proposed value after the waiting period has passed.
Copy
```
function updatePerformanceFee() external;
```
***
**proposeNewEntryAndExitFee**
Proposes new entry and exit fees, starting a timer before the changes can be finalized.
Copy
```
function proposeNewEntryAndExitFee(uint256 _newEntryFee, uint256 _newExitFee) external;
```
**Parameters:**
* `_newEntryFee`: The proposed new entry fee, in basis points.
* `_newExitFee`: The proposed new exit fee, in basis points.
**deleteProposedEntryAndExitFee**
Cancels the proposed entry and exit fees, resetting the proposal.
Copy
```
function deleteProposedEntryAndExitFee() external;
```
**updateEntryAndExitFee**
Finalizes the entry and exit fee updates after the waiting period.
Copy
```
function updateEntryAndExitFee() external;
```
***
#### Portfolio Settings
**updateTransferability**
Updates the transferability settings of the portfolio token, determining whether tokens can be transferred and whether transfers to the public are allowed.
Copy
```
function updateTransferability(bool _transferable, bool _publicTransfer) external;
```
**Parameters:**
* `_transferable`: Enables or disables the ability to transfer portfolio tokens.
* `_publicTransfer`: Allows or disallows transferring portfolio tokens to the public (non-whitelisted addresses).
***
**convertPrivateFundToPublic**
Converts a private portfolio to a public one, allowing broader access to investors.
Copy
```
function convertPrivateFundToPublic() external;
```
***
**updateMinPortfolioTokenHoldingAmount**
Sets the minimum amount of portfolio tokens that must be held or transacted, enforcing investment thresholds.
Copy
```
function updateMinPortfolioTokenHoldingAmount(uint256 _minPortfolioTokenHoldingAmount) external;
```
**Parameters:**
* `_minPortfolioTokenHoldingAmount`: The new minimum portfolio token amount required for transactions.
***
**updateInitialPortfolioAmount**
Updates the initial amount of the portfolio, setting a new starting value for the portfolio tokens.
Copy
```
function updateInitialPortfolioAmount(uint256 _newAmount) external;
```
**Parameters:**
* `_newAmount`: The new initial portfolio amount.
***
#### Treasury Management
**updateAssetManagerTreasury**
Changes the address where asset management fees are accumulated.
Copy
```
function updateAssetManagerTreasury(address _newAssetManagerTreasury) external;
```
**Parameters:**
* `_newAssetManagerTreasury`: The new treasury address for asset management fees.
***
#### User Whitelist Management
**whitelistUser**
Adds users to the whitelist, allowing them to deposit into the portfolio.
Copy
```
function whitelistUser(address[] calldata users) external;
```
**Parameters:**
* `users`: An array of user addresses to be whitelisted.
***
**removeWhitelistedUser**
Removes users from the whitelist, revoking their ability to deposit.
Copy
```
function removeWhitelistedUser(address[] calldata users) external;
```
**Parameters:**
* `users`: An array of user addresses to be removed from the whitelist.
# Product Roadmap
Velvet is making advanced onchain finance feel as simple, fast, and intelligent as using a modern trading app, while preserving the openness and self-custody of DeFi.
Velvet is building AI-powered onchain trading and portfolio management terminal.
Our roadmap is focused on three core goals:
1. Make onchain trading faster, smarter, and easier to access.
2. Expand Velvet into a multi-chain execution layer for traders, agents, and applications.
3. Bring AI assisted trading to our users.
*This roadmap is directional and may evolve based on user feedback, security reviews, ecosystem priorities, and market conditions.*
### Completed Milestones
#### Foundation & Beta Launches
* [x] BNB Chain beta launch
* [x] Referral program and points system launch
* [x] Arbitrum beta development, testing, security audits, and launch
* [x] Deployment on Base
#### Intent-Based Trading Infrastructure
* [x] Intent OS development and internal testing
* [x] Intent OS pilot with solver integration
* [x] Intent-based execution module
* [x] Security audits and open trading competition for Intent OS
#### Multi-Chain Trading Terminal
* [x] Trading Terminal release across Base, Solana, BNB Chain, Hyperliquid, Ethereum, Sonic, and Monad
* [x] Development and launch of the new UI/UX
* [x] Real-time PnL tracking by position
* [x] Integrated wallet for faster trading without repeated token approvals
#### AI & DeFAI Capabilities
* [x] DeFAI framework integration into the main Velvet app
* [x] Trading and DeFi execution through the AI copilot
* [x] Fund management API for strategy automation
* [x] x402 Integration
* [x] 8004 Integration
#### Governance, Incentives & Token Launch
* [x] Points system upgrade
* [x] New referral program with fee sharing and affiliate rewards
* [x] Staking module
* [x] Velvet Gems Launch
* [x] Token launch, also known as TGE
* [ ] Governance module
#### Advanced Execution Engine
* [x] Limit orders
* [x] Wallet Triggers
* [x] DCA Orders
* [x] Turbo Buys & Sells
#### Security & Reliability
* [x] Real-time security monitoring
* [x] Bug bounty program
* [x] Multiple audits across key product and protocol components
### Upcoming Roadmap
#### AI-Powered Trading & Automation
Velvet is expanding from manual trading into agentic execution, where users can discover opportunities, generate strategies, and execute trades through AI-powered workflows.
Planned upgrades include:
* [ ] DeFAI Telegram trading bot across Solana, Base, and BNB Chain
* [ ] Individual portfolio management powered by AI, also known as Prompt-to-Strategy
* [ ] AI-assisted trading workflows for strategy discovery, execution, and portfolio optimization
#### Velvet X (Invite Only App)
* [x] Social graph across millions of top KOL and traders
* [ ] New Social + AI feed
* [x] Redesigned all-chain experience
* [x] Mobile-first trading UX
#### Advanced Execution Engine
Velvet will continue improving execution quality, trade control, and automation for active traders.
Planned upgrades include:
* [x] TWAP orders
* [ ] Additional advanced order types
* [x] Wallet tracking
* [ ] Twitter tracking
* [ ] Copy trading
#### Chain Abstraction & Omni-Chain Trading
Velvet is building toward a more seamless multi-chain trading experience where users can access liquidity and execution across chains without needing to manually manage every network interaction.
Planned upgrades include:
* [ ] Chain abstraction
* [ ] Omni-chain execution module
* [ ] Cross-chain trading and portfolio workflows
#### Portfolio Management & Trading API
Velvet’s infrastructure will continue expanding for teams, protocols, funds, and applications that want to build on top of Velvet’s trading and portfolio management stack.
Planned upgrades include:
* [ ] Portfolio Management API upgrade
* [ ] Trading API upgrade
* [ ] Expanded support across Ethereum, Base, Hyperliquid, BNB Chain, and Solana
* [ ] Key management improvements
* [ ] Improved dashboards and operational tooling
#### Velvet Network for DeFAI
Velvet is exploring dedicated infrastructure for the DeFAI ecosystem, designed to support AI agents, trading applications, strategy automation, and onchain execution at scale.
Planned upgrades include:
* [ ] Velvet blockchain network for DeFAI
* [ ] Infrastructure for agent-driven trading and portfolio management
* [ ] Execution rails for DeFAI applications and AI-native financial products
#### Privacy Capabilities
Velvet plans to add privacy-focused features that improve user protection, trading discretion, and overall security.
Planned upgrades include:
* [ ] Privacy capabilities for trading and portfolio management
* [ ] Additional protections for users, strategies, and sensitive trading activity
# Security & Audits
## Verified & Audited
All the contracts are open for external code auditors / white hats to verify the code. We're constantly running bug bounties and conducting security audits.
Velvet.Capital has undergone 7 audits with leading firms such as Peckshield, Softstack (fka Chainsulting), Resonance Security, Shellboxes as well as an open audit competitions with Hats Finance.
Final reports can be found here:
## Real-Time Security Monitoring
Velvet.Capital partnered with Forta (the largest network of security intel in Web3) to get machine learning-generated intelligence about exploits, scams and other threats from a community of leading security experts.
Velvet.Capital also uses Open Zeppelin Defender 2.0, a security platform to code, audit, deploy, monitor, and operate the protocol, including its native integration with Forta.
Finally, Tenderly provides transaction simulation and real-time alerts for on-chain events, including any irregular activity.
## Bug Bounty
We currently have two bug bounties live, please refer to the scope and rewards on Immunefi and Hats Finance:[ ](https://app.hats.finance/bug-bounties/velvet-capital-0xb495c253b33abd5cea007df2ff8ee9f61bc6d35e/rewards)
[\
\- Velvet Capital Bug Bounty Program](https://app.hats.finance/bug-bounties/velvet-capital-0xb495c253b33abd5cea007df2ff8ee9f61bc6d35e/rewards) (Hats Finance)
[- Velvet Capital Bug Bounty Program](https://immunefi.com/bug-bounty/velvetcapital/) (Immunefi)
# Links
🔗 Website:
📲 New App (VelvetX): [https://x.velvet.capital](https://x.velvet.capital/)
📲 App: \
\
📲 Previous version (beta): \
\
🌠 NFT: \
\
🐦 Twitter: \
\
🌐 Telegram: \
\
📰 Blog & Newsletter: \
\
💾 Medium: \
\
🏠 Discord: \
\
🗂️ Docs: \
\
📇 DeBank:
