POST /build/launch

An unsigned, simulated token launch.

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

Body

Field	Type	Required	Meaning
`wallet`	string	yes	A 0x address
`name`	string	yes	Up to 64 bytes
`symbol`	string	yes	Up to 32 bytes
`marketCapUsd`	string		A decimal amount in whole units, as a string: “0.05”
`marketCapPair`	string		A decimal amount in whole units, as a string: “0.05”
`supply`	string		Whole tokens, 1 to 1,000,000,000,000; default 1,000,000,000
`pair`	string		“BNB” (default), a listed symbol, or any BEP20 address
`firstBuy`	string		A buy in the pair currency, inside the launch transaction
`firstBuyTo`	object[]		Split the first buy; must add to 100. The dead address burns.
`firstBuyTo[].wallet`	string	yes	A 0x address
`firstBuyTo[].pct`	number	yes	Its share of the first buy, in percent
`slippagePct`	number
`image`	string		The logo: an https:// link to a PNG, JPG, GIF or WebP, up to 5 MB. Required unless metadataURI is sent (and its metadata must have an image).
`description`	string
`website`	string
`x`	string
`telegram`	string
`metadataURI`	string
`burnPct`	number		Share of the creator royalty that buys back and burns, for ever
`royaltyTo`	string		A 0x address
`shape`	`flat` · `stepped` · `steep` or object[]		How the supply is laid across prices: “flat” (default), “stepped”, “steep”, or 1 to 4 ranges
`shape[].fromPct`	number	yes	Where the range starts, as a percent of 46,000 ticks (about 100x in price) above where the shape begins
`shape[].toPct`	number	yes	Where it ends, on the same scale. The last range always runs to the top price, so no shape caps the price
`shape[].bps`	integer	yes	Its share of the shaped supply; all ranges add to 10,000
`feeTier`	`100` · `500` · `2500` · `10000`

Response

Field	Type	Required	Meaning
`wallet`	string	yes	A 0x address
`token`	string	yes	The new token’s address, known before sending
`name`	string	yes
`symbol`	string	yes
`supply`	object	yes	The total supply
`supply.amount`	string	yes	A decimal amount in whole units, as a string: “0.05”
`supply.wei`	string	yes	The same amount in the smallest unit, an integer as a string
`pair`	object	yes	The pair currency
`pair.address`	string	yes	The pair currency’s contract (WBNB for BNB)
`pair.decimals`	integer	yes	Its decimals
`pair.symbol`	string	yes	Its symbol, e.g. BNB
`pair.priced`	boolean	yes	Whether it has a dollar price
`pair.note`	string
`opening`	object	yes
`opening.marketCapPair`	number	yes	A number, not a string: the opening cap the chosen tick gives
`opening.marketCapUsd`	number or null	yes
`opening.driftFromAskedPct`	number	yes	Ticks are ~2% apart on the 1% tier, so the cap opens near, not at, what was asked
`feeTier`	integer	yes	The pool fee tier (10000 = 1%)
`firstBuy`	object or null	yes	The first buy: what it spends and the fewest tokens it accepts; null without one
`firstBuy.spend`	object	yes
`firstBuy.spend.amount`	string	yes	A decimal amount in whole units, as a string: “0.05”
`firstBuy.spend.wei`	string	yes	The same amount in the smallest unit, an integer as a string
`firstBuy.minTokens`	object	yes
`firstBuy.minTokens.amount`	string	yes	A decimal amount in whole units, as a string: “0.05”
`firstBuy.minTokens.wei`	string	yes	The same amount in the smallest unit, an integer as a string
`launchFee`	object	yes	The launch fee (0: free)
`launchFee.amount`	string	yes	A decimal amount in whole units, as a string: “0.05”
`launchFee.wei`	string	yes	The same amount in the smallest unit, an integer as a string
`creatorFeeRecipient`	string	yes	Where the royalty is paid
`royalty`	object	yes	The royalty choice, and one sentence saying it
`royalty.kind`	`keep` · `split` · `holders`	yes
`royalty.burnPct`	number	yes
`royalty.to`	string	yes	A 0x address
`royalty.explain`	string	yes
`shape`	string	yes	The supply shape
`firstBuyTo`	object[] or null	yes	How the first buy is split, or null
`firstBuyTo[].wallet`	string	yes	A 0x address
`firstBuyTo[].pct`	number	yes
`salt`	string	yes	The salt that fixes the token’s address
`metadata`	object or null	yes	The stored logo and details, or null
`metadata.uri`	string	yes
`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”
`explain`	string	yes

A real response

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

{
  "wallet": "0x2bf842241129be12f3a0e4f21e25d2fd43d9e6da",
  "token": "0x8fbb86493b27fe77f70fb87b78967e894946950b",
  "name": "Fixture",
  "symbol": "FIX",
  "supply": {
    "amount": "1000000000.0",
    "wei": "1000000000000000000000000000"
  },
  "pair": {
    "address": "0xae13d989dac2f0debff460ac112a837c89baa7cd",
    "symbol": "BNB",
    "decimals": 18,
    "priced": true
  },
  "opening": {
    "marketCapPair": 0.019149086912313856,
    "marketCapUsd": 14.810286799721782,
    "driftFromAskedPct": -1.2647546685214617
  },
  "feeTier": 10000,
  "firstBuy": {
    "spend": {
      "amount": "0.0003",
      "wei": "300000000000000"
    },
    "minTokens": {
      "amount": "14128715.241459207609295845",
      "wei": "14128715241459207609295845"
    }
  },
  "launchFee": {
    "amount": "0.0",
    "wei": "0"
  },
  "creatorFeeRecipient": "0xe007fff1396b1d0f5293b2e589ad2d35e878b300",
  "royalty": {
    "kind": "holders",
    "burnPct": 100,
    "to": "0xe007fff1396b1d0f5293b2e589ad2d35e878b300",
    "explain": "All of the royalty buys back and burns the token, for ever."
  },
  "shape": "flat",
  "firstBuyTo": [
    {
      "wallet": "0x000000000000000000000000000000000000dead",
      "pct": 60
    },
    {
      "wallet": "0x2bf842241129be12f3a0e4f21e25d2fd43d9e6da",
      "pct": 40
    }
  ],
  "salt": "0xe59d7f75aa908d7ec895fbb622f09249b59f48a1344c36acc582db9d1084b956",
  "metadata": null,
  "requires": [],
  "tx": {
    "chainId": 97,
    "to": "0x5d96cbf410468950F92A1f544Ef924B24a23fe66",
    "data": "0x2d7d962e0000000000000000000000000000000000000000000000000000000000000020…",
    "value": "300000000000000",
    "gas": "16777216"
  },
  "simulation": {
    "ran": true,
    "ok": true
  },
  "cost": {
    "gasPriceWei": "100000000",
    "maxWei": "1977721600000000",
    "max": "0.0019777216"
  },
  "explain": "Launch Fixture ($FIX), 1,000,000,000 tokens, opening at about $14.8103 market cap, with a first buy of 0.0003 BNB. Royalty: all bought back and burned, for ever."
}

Errors

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

MISSING_MARKET_CAP: A launch needs its opening market cap.
NO_PRICE: The pair currency has no live dollar price, so a dollar market cap cannot be converted.
INVALID_SUPPLY: The supply is outside 1 to 1,000,000,000,000 whole tokens.
INVALID_LAUNCH: A launch field breaks one of the launch rules.
INVALID_SHAPE: The supply shape is not one of the presets or a valid list of ranges.
SHAPE_BELOW_LADDER: The shape no longer fits this launch: its price layout moved with the dollar price since the launch was built.
INVALID_BURN: burnPct is not 0, 1–99 (with at most two decimals) or 100.
CONFLICTING_ROYALTY: royaltyTo and a burnPct above 0 were both sent.
CONFLICTING_METADATA: metadataURI and the details (image, description, …) were both sent.
INVALID_METADATA_URI: metadataURI is not an https:// or ipfs:// link.
INVALID_IMAGE: The image link could not be used.
IMAGE_TOO_LARGE: The image is larger than 5 MB.
UNSUPPORTED_IMAGE: The image is not PNG, JPG, GIF or WebP, or the upload body is not the image itself.
UPLOADS_BUSY: Uploads are busy right now.
STORAGE_UNAVAILABLE: The image could not be stored just now. Nothing was launched.
UNSUPPORTED_PAIR: The pair is not BNB, a listed symbol, or a readable BEP20 token.
LAUNCHES_PAUSED: Launches are paused on the factory right now.
INSUFFICIENT_BALANCE: The wallet cannot pay for this: the amount, or the gas, or both.
TOO_MUCH_GAS: This launch needs more gas than one BSC transaction may use.
SIMULATION_FAILED: The transaction would revert on chain, so it was not returned. Nothing was sent.
RATE_LIMITED: Too many requests from this address in the last minute.