POST /v1/intent

This endpoint allows you to create a new bot intent for token sniping using a custodial bot, specifying conditions and parameters under which the intent will execute during a token launch. See wallet intents for non-custodial sniping.

---

Request

Endpoint

POST https://snipe.merkle.io/v1/intent

Body

{
  // Required fields
  "chainId": 1,
  "wallet": "<wallet address>",
  "tokenAddress": "<token address>",
  "bribe": "<bribe amount in wei>",
  "buyAmount": "<buy amount in wei>",
  "expiry": 2800998888, // expiry timestamp in seconds

  // Optional fields
  "maxBuyTax": 0.2, // between 0 and 1
  "maxSellTax": 0.2, // between 0 and 1
  "minIn": "<min in amount in wei>",
  "minOut": "<min out amount in token units>",
  "minLiquidity": "<min liquidity in cents>",
  "feeBps": 100, // 1% fee on the buy amount
  "feeRecipient": "<fee recipient address>",
  "firstOrFail": true, // or false
  "maxSlippageBps": 1000, // 10%
  "gasTip": "1000000000" // in wei (e.g., 1 gwei)
}

Field	Type	Required	Description
chainId	number	Yes	Blockchain network ID (e.g., 1 for Ethereum).
wallet	string	Yes	Wallet address to use for the transaction.
tokenAddress	string	Yes	Address of the token to be purchased.
bribe	string	Yes	Bribe amount in wei for miners or block builders.
buyAmount	string	Yes	Amount to purchase in wei.
expiry	number	Yes	Expiry timestamp for the intent (UNIX format in seconds).
webhookUrl	string	Yes	Url for signature webhook for this intent.
notificationWebhookUrl	string	No (but recommended)	Url for notifications about this intent.
maxBuyTax	number	No	Maximum acceptable buy tax (0 to 1).
maxSellTax	number	No	Maximum acceptable sell tax (0 to 1).
minIn	string	No	Minimum input amount in wei.
minOut	string	No	Minimum output amount in token units.
minLiquidity	string	No	Minimum liquidity in cents (e.g., 10000 for $100).
feeBps	number	No	Fee in basis points (e.g., 100 for 1%).
feeRecipient	string	No	Address to receive the fee.
firstOrFail	boolean	No	Whether the intent should only be included in the first bundle.
maxSlippageBps	number	No	Maximum slippage in basis points (e.g., 1000 for 10%).
gasTip	string	No	Gas tip in wei (e.g., 1000000000 for 1 gwei).

---

Response

200

{
    id: "<uuid>",
    status: "pending" | "completed" | "expired" | "cancelled" | "error";
    error: "balance_too_low",
			 | "allowance_too_low",
			 | "balance_fetch_error",
			 | "allowance_fetch_error",
			 | "not_included_in_bundle",
			 | "unknown"
			 | null,
    txHash: null,
    tokenAddress: "0x...",
    wallet: "0x...",
    chainId: 1,
    bribe: "100000000000", // in wei
    buyAmount: "100000000000", // in wei
    maxBuyTax: 0.5,
    maxSellTax: 0.5,
    maxSlippageBps: 1000,
    minBuy: "1000000", // in wei
    minOut: "1000000", // in wei
    createdAtMs: 99999999, // in milliseconds 
    gasTip: 1000000000,
    token: {
	    chainId: 1,
	    address: "0x...",
	    deployer: "0x...",
	    deployerHash: "0x...",
	    deployerBlocknumber: 190000000,
	    deployerTimestamp: 99999999, // in seconds
	    launchedAtBlocknumber: null,
	    launchBuyTax: null,
	    launchStatus: "not_launched",
	    launchLiquidity: null,
	    launchProcessingTime: null,
	    launchSellTax: null,
	    launchedAtTxHash: null,
	    totalSupply: "9999999999999",
	    name: "Token name",
	    iconUrl: "",
	    symbol: "TKN",
	    decimals: 9,
	    launchedAtMs: null,
    }
}