POST /build/buy

An unsigned, simulated buy.

POST https://marketmayhem.co/api/v1/build/buy

Body

Field	Type	Required	Meaning
wallet	string	yes	The wallet that will sign and send
token	string	yes	A 0x address
amount	string	yes	exact “in”: what is spent; exact “out”: what is received
exact	in · out		in (default): amount is spent; out: amount is received
slippageBps	integer		Basis points; default 50 (0.5%)
referrer	string or null		Paid the referral cut inside the trade. Omit: your API key’s wallet; null: nobody.

Response

Field	Type	Required	Meaning
token	object	yes	The token traded
token.address	string	yes	A 0x address
token.symbol	string	yes
token.pool	string	yes	A 0x address
token.feeTier	integer	yes
token.pair	object	yes
token.pair.address	string	yes	The pair currency’s contract (WBNB for BNB)
token.pair.decimals	integer	yes	Its decimals
token.pair.symbol	string	yes	Its symbol, e.g. BNB
side	buy · sell	yes	buy: pay the pair currency, get the token; sell: the reverse
exact	in · out	yes	in: pay is fixed; out: receive is fixed
slippageBps	integer	yes	The tolerance the limit is set from
pay	object	yes	What is spent
pay.amount	string	yes	A decimal amount in whole units, as a string: “0.05”
pay.wei	string	yes	The same amount in the smallest unit, an integer as a string
pay.symbol	string	yes	The currency, e.g. BNB or the token’s ticker
receive	object	yes	What comes back, at the price now
receive.amount	string	yes	A decimal amount in whole units, as a string: “0.05”
receive.wei	string	yes	The same amount in the smallest unit, an integer as a string
receive.symbol	string	yes	The currency, e.g. BNB or the token’s ticker
limit	object	yes	The floor (or ceiling) written into the trade: it reverts rather than fill worse
limit.amount	string	yes	A decimal amount in whole units, as a string: “0.05”
limit.wei	string	yes	The same amount in the smallest unit, an integer as a string
limit.kind	minReceive · maxPay	yes
siteFee	object	yes	The site fee this trade pays
siteFee.amount	string	yes	A decimal amount in whole units, as a string: “0.05”
siteFee.wei	string	yes	The same amount in the smallest unit, an integer as a string
siteFee.symbol	string	yes	The currency, e.g. BNB or the token’s ticker
siteFee.bps	integer	yes	Its rate, in basis points
priceImpactPct	number	yes	How far this trade moves the price, in per cent
wallet	string	yes	The wallet it was built for
referrer	object or null	yes	Who is paid the referral cut, and how much, or null
referrer.address	string	yes	A 0x address
referrer.bps	integer	yes	Its cut, in basis points of the trade
referrerNote	string		Why your key’s wallet was not used as referrer, when it was not
requires	object[]	yes	One-time steps to send and wait for first, in order. Empty when the wallet is ready.
requires[].step	string	yes	e.g. “approve-permit2”, “approve-router”, “approve-factory”
requires[].explain	string	yes
requires[].tx	object	yes	An unsigned transaction: sign it with the wallet and send it.
requires[].tx.chainId	integer	yes	56 BSC mainnet, 97 BSC testnet
requires[].tx.to	string	yes	A 0x address
requires[].tx.data	string	yes	The call data: send it exactly as it is
requires[].tx.value	string	yes	BNB to send with it, in wei
requires[].tx.gas	string		The simulated gas plus a margin. Absent while a step in requires is still needed.
tx	object	yes	An unsigned transaction: sign it with the wallet and send it.
tx.chainId	integer	yes	56 BSC mainnet, 97 BSC testnet
tx.to	string	yes	A 0x address
tx.data	string	yes	The call data: send it exactly as it is
tx.value	string	yes	BNB to send with it, in wei
tx.gas	string		The simulated gas plus a margin. Absent while a step in requires is still needed.
simulation	object	yes	The simulation against the chain, from the wallet
simulation.ran	boolean	yes	Whether it was simulated: not while a step in requires is still needed
simulation.ok	boolean	yes	It would succeed if sent now
cost	object	yes	The most the transaction can cost in gas, in BNB.
cost.gasPriceWei	string	yes	The same amount in the smallest unit, an integer as a string
cost.maxWei	string	yes	The same amount in the smallest unit, an integer as a string
cost.max	string	yes	A decimal amount in whole units, as a string: “0.05”
expiresAt	string	yes	The on-chain deadline
explain	string	yes	One sentence to show before signing

A real response

Captured from BSC testnet, exactly as the API sent it (long calldata shortened).

{
  "token": {
    "address": "0x136bfd5f42250a568ce06ed1b145729b400e391c",
    "symbol": "BRNT",
    "pool": "0x0c779f6d50f5d27df85a84e8fc15e66202076e6d",
    "feeTier": 10000,
    "pair": {
      "address": "0xae13d989dac2f0debff460ac112a837c89baa7cd",
      "decimals": 18,
      "symbol": "BNB"
    }
  },
  "side": "buy",
  "exact": "in",
  "slippageBps": 50,
  "pay": {
    "amount": "0.0005",
    "wei": "500000000000000",
    "symbol": "BNB"
  },
  "receive": {
    "amount": "1780786.99943692577655049",
    "wei": "1780786999436925776550490",
    "symbol": "BRNT"
  },
  "limit": {
    "kind": "minReceive",
    "amount": "1771883.064439741147667737",
    "wei": "1771883064439741147667737"
  },
  "siteFee": {
    "amount": "0.000005",
    "wei": "5000000000000",
    "symbol": "BNB",
    "bps": 100
  },
  "priceImpactPct": 0.3781,
  "wallet": "0x2bf842241129be12f3a0e4f21e25d2fd43d9e6da",
  "referrer": null,
  "requires": [],
  "tx": {
    "chainId": 97,
    "to": "0xF265f08Ac720B4dCD6BA1928C5F13b0ff0bE207d",
    "data": "0x3593564c0000000000000000000000000000000000000000000000000000000000000060…",
    "value": "500000000000000",
    "gas": "195949"
  },
  "simulation": {
    "ran": true,
    "ok": true
  },
  "cost": {
    "gasPriceWei": "100000000",
    "maxWei": "519594900000000",
    "max": "0.0005195949"
  },
  "expiresAt": "2026-09-26T09:12:57.000Z",
  "explain": "Buy about 1,780,790 BRNT for 0.0005 BNB (at least 1,771,880 BRNT). Site fee 0.000005 BNB."
}

Errors

Every error is { "error": { "code", "message", "fix"? } }. This endpoint can answer:

• UNKNOWN_TOKEN: That address is not a token launched on Market Mayhem.
• INVALID_AMOUNT: The amount is not a positive decimal number, or both/neither of amount and percent were sent.
• INSUFFICIENT_BALANCE: The wallet cannot pay for this: the amount, or the gas, or both.
• SIMULATION_FAILED: The transaction would revert on chain, so it was not returned. Nothing was sent.
• SELF_REFERRAL: A wallet cannot be its own referrer.
• REFERRER_NOT_REGISTERED: The referrer is neither a registered referrer nor a creator, so a trade cannot pay it.
• POOL_TOO_THIN: The pool cannot fill that size in one trade.
• CHAIN_UNREACHABLE: The chain could not be read just now. Nothing was sent.
• RATE_LIMITED: Too many requests from this address in the last minute.