# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.velvet.capital/velvet-capital-ai-powered-onchain-trading-terminal/intent-execution-api-trading-and-defi.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.