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

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

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)

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)

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:

      jsonCopy code{
  "error": "Missing required field: amount"
}

  • 404 Not Found: The requested resource cannot be found.

    • Example response:

      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: https://metasolvertest.velvetdao.xyz/api-docs/#/default/post_best_quotes

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

PreviousCreating a Shared VaultNextBuilding a Custom App

Last updated