Developers

POST /api/auth/wallet
Content-Type: application/json

{
  "address": "0xYourWalletAddress",
  "signature": "<signature>",
  "message": "Sign in to Livo\nTimestamp: <unix_ms>"
}

// Response:
{ "token": "eyJhbGci..." }

if (creator takes a post-graduation LP fee):
    use LivoFactoryUniV4Unified   // graduates to Uniswap V4
else:
    use LivoFactoryUniV2Unified   // graduates to Uniswap V2

// V2 — LivoFactoryUniV2Unified (graduates to Uniswap V2)
function createToken(
    TokenSetupTiered   tokenSetup,
    TaxConfigs         taxConfigs,
    SupplyShare[]      buyOnDeployShares,
    AntiSniperConfigs  antiSniperConfigs,
    CreatorVault[]     creatorVaults,
    address            referral
) payable returns (address token);

// V4 — LivoFactoryUniV4Unified (graduates to Uniswap V4; adds univ4Configs)
function createToken(
    TokenSetupTiered   tokenSetup,
    TaxConfigs         taxConfigs,
    UniV4Configs       univ4Configs,      // V4 only, position 3
    SupplyShare[]      buyOnDeployShares,
    AntiSniperConfigs  antiSniperConfigs,
    CreatorVault[]     creatorVaults,
    address            referral
) payable returns (address token);

struct TokenSetupTiered {
    string        name;
    string        symbol;
    bytes32       salt;           // mined so the address ends in 0x1110 (see Vanity Salt)
    FeeShare[]    feeShares;      // trading-fee recipients; shares sum to 10000
    LiquidityTier liquidityTier;  // 0 = THIN, 1 = DEFAULT, 2 = THICK
}

struct FeeShare {
    address account;
    uint256 shares;               // bps, > 0; array sums to exactly 10000
    bool    directFeesEnabled;    // at most ONE entry may be true
}

struct TaxConfigs {
    uint16 buyTaxBps;             // long-term buy tax; 0 disables static tax
    uint16 sellTaxBps;            // long-term sell tax; 0 disables static tax
    uint32 taxDurationSeconds;    // static-tax window; 0 disables (then bps must be 0)
    bool   startTaxFromLaunch;    // true: window from launch; false: from graduation
    uint16 buyTaxDecayStartBps;   // optional launch-tax decay start (buy); 0 = none
    uint16 sellTaxDecayStartBps;  // optional launch-tax decay start (sell); 0 = none
    uint32 taxDecayDuration;      // decay window; 0 disables; max 20 min
}

struct UniV4Configs {
    bool   renounceOwnership;   // true → deployed ownerless; false → owner = msg.sender
    uint16 lpFeeBps;            // post-graduation hook fee: must be 100 or 50
}

struct SupplyShare {
    address account;
    uint256 shares;   // bps, > 0; array sums to exactly 10000
}

// tier = tokenSetup.liquidityTier
// totalLockedInVaultsBps = sum of creatorVaults[].supplyBps (0 if no vaults)
uint256 maxTokens = factory.maxBuyOnDeploy(tier, totalLockedInVaultsBps);

// Buy any amount up to maxTokens. Passing maxTokens is the max-buy special
// case: the deploy-buy reaches graduation, so the token graduates on deploy.
uint256 tokenAmount = maxTokens;

// quoteBuyOnDeploy inflates the raw curve cost by the launch buy fee (tax /
// trading fee). The V4 factory appends univ4Configs as a 5th arg.
uint256 value = factory.quoteBuyOnDeploy(tier, tokenAmount, totalLockedInVaultsBps, taxConfigs);

// Send value as msg.value; the bought tokenAmount is split across recipients.
SupplyShare[] buyOnDeployShares = [SupplyShare(recipient, 10000)];

struct AntiSniperConfigs {
    uint16    maxBuyPerTxBps;          // 10..300 (0.1%..3% of supply)
    uint16    maxWalletBps;            // 10..300, and >= maxBuyPerTxBps
    uint40    protectionWindowSeconds; // 0 disables; else 60..86400 (1min..24h)
    address[] whitelist;               // <= 20 addresses; bypass caps in the window
}

struct CreatorVault {
    address owner;
    uint256 supplyBps;       // non-zero multiple of 500 (5%); sum across vaults <= 3000 (30%)
    uint256 cliffSeconds;    // pure lock-up before vesting
    uint256 vestingSeconds;  // linear vesting after the cliff
}

import { keccak256, concat, toBytes } from "viem";

const PROXY_PREFIX = "0x3d602d80600a3d3981f3363d3d373d3d3d363d73";
const PROXY_SUFFIX = "0x5af43d82803e903d91602b57fd5bf3";

// deployer = the account that will send the createToken tx
function findVanitySalt(factoryAddress, tokenImplementation, deployer) {
  const initcodeHash = keccak256(
    concat([PROXY_PREFIX, tokenImplementation, PROXY_SUFFIX])
  );
  const buffer = new Uint8Array(85);
  buffer[0] = 0xff;
  buffer.set(toBytes(factoryAddress), 1);
  buffer.set(toBytes(initcodeHash), 53);

  // effective CREATE2 salt = keccak256(deployer ++ salt)
  const saltPreimage = new Uint8Array(52);
  saltPreimage.set(toBytes(deployer), 0);

  const salt = crypto.getRandomValues(new Uint8Array(32));
  for (;;) {
    saltPreimage.set(salt, 20);
    buffer.set(keccak256(saltPreimage, "bytes"), 21);
    const hash = keccak256(buffer);
    if (hash.endsWith("1110")) {
      const saltHex = "0x" + Array.from(salt,
        (b) => b.toString(16).padStart(2, "0")).join("");
      return { salt: saltHex, tokenAddress: "0x" + hash.slice(26) };
    }
    for (let i = 31; i >= 0; i--) {
      if (salt[i] < 255) { salt[i]++; break; }
      salt[i] = 0;
    }
  }
}

import { keccak256, encodeFunctionData } from "viem";

// tokenSetup, taxConfigs, antiSniperConfigs built as in Step 2; salt from the Vanity Salt section.
const data = encodeFunctionData({
  abi: factoryAbi,
  functionName: "createToken",
  // V2 factory args — the V4 factory inserts univ4Configs ({ renounceOwnership, lpFeeBps })
  // in position 3, right after taxConfigs.
  args: [tokenSetup, taxConfigs, buyOnDeployShares, antiSniperConfigs, creatorVaults, referral],
});

const fees = await publicClient.estimateFeesPerGas();
const tx = {
  type: "eip1559",
  chainId,
  nonce: await publicClient.getTransactionCount({ address: account.address }),
  to: factoryAddress,
  data,
  value: 0n, // > 0 only for a deployer buy (buyOnDeployShares non-empty)
  gas: await publicClient.estimateGas({ account, to: factoryAddress, data }),
  maxFeePerGas: fees.maxFeePerGas,
  maxPriorityFeePerGas: fees.maxPriorityFeePerGas,
};

const signedTx = await walletClient.signTransaction(tx);
const txHash = keccak256(signedTx);

POST /api/tokens/create
Authorization: Bearer <jwt_token>
Content-Type: multipart/form-data

{
  "success": true,
  "txHash": "0x...",
  "imageUrl": "https://..."
}

const hash = await publicClient.sendRawTransaction({
  serializedTransaction: signedTx,
});
// hash === txHash submitted in Step 4

PATCH /api/tokens/image
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "txHash": "0x...",            // or "tokenAddress": "0x..."
  "imageUrl": "ipfs://<cid>"    // IPFS only (ipfs:// or /ipfs/<cid> gateway URL)
}

// Response:
{ "success": true, "txHash": "0x...", "imageUrl": "https://...mypinata.cloud/ipfs/<cid>" }

event TokenCreated(
    address indexed token,
    string name,
    string symbol,
    address tokenOwner,
    address launchpad,
    address graduator,
    address feeHandler
)

event TokenLaunched(
    address indexed token,
    uint256 graduationThreshold,
    uint256 maxExcessOverThreshold
)

import {
  createPublicClient,
  createWalletClient,
  http,
  keccak256,
  encodeFunctionData,
  zeroAddress,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";

const API_BASE = "https://livo.trade";
const FACTORY_ADDRESS = "0x..."; // LivoFactoryUniV2Unified — see contracts repo

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const walletClient = createWalletClient({ account, chain: mainnet, transport: http() });

// 1. Authenticate
const timestamp = Date.now();
const message = `Sign in to Livo\nTimestamp: ${timestamp}`;
const signature = await walletClient.signMessage({ account, message });
const { token: jwt } = await fetch(`${API_BASE}/api/auth/wallet`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ address: account.address, signature, message }),
}).then((r) => r.json());

// 2. Build the createToken structs (minimal token: single fee receiver, no tax,
//    no anti-sniper, no vaults, no buy-on-deploy, DEFAULT liquidity tier).
const name = "My Token";
const symbol = "MTK";
const feeShares = [
  { account: account.address, shares: 10000n, directFeesEnabled: false },
];
const taxConfigs = {
  buyTaxBps: 0, sellTaxBps: 0, taxDurationSeconds: 0, startTaxFromLaunch: false,
  buyTaxDecayStartBps: 0, sellTaxDecayStartBps: 0, taxDecayDuration: 0,
};
const antiSniperConfigs = {
  maxBuyPerTxBps: 0, maxWalletBps: 0, protectionWindowSeconds: 0, whitelist: [],
};
const buyOnDeployShares = []; // empty ⇒ no deployer buy (value must be 0)
const creatorVaults = [];

// The factory clones a taxable or base impl depending on the tax config; mine the
// vanity salt against the impl this view returns for THESE exact inputs.
const tokenImplementation = await publicClient.readContract({
  address: FACTORY_ADDRESS,
  abi: factoryAbi,
  functionName: "previewTokenImplementation",
  args: [feeShares, buyOnDeployShares, taxConfigs, antiSniperConfigs],
});
const { salt } = findVanitySalt(FACTORY_ADDRESS, tokenImplementation, account.address);

const tokenSetup = { name, symbol, salt, feeShares, liquidityTier: 1 /* DEFAULT */ };
const data = encodeFunctionData({
  abi: factoryAbi,
  functionName: "createToken",
  // V2 args; the V4 factory inserts { renounceOwnership, lpFeeBps } in position 3.
  args: [tokenSetup, taxConfigs, buyOnDeployShares, antiSniperConfigs, creatorVaults, zeroAddress],
});

// 3. Sign the transaction offline and precompute the txHash
const fees = await publicClient.estimateFeesPerGas();
const tx = {
  type: "eip1559",
  chainId: mainnet.id,
  nonce: await publicClient.getTransactionCount({ address: account.address }),
  to: FACTORY_ADDRESS,
  data,
  value: 0n,
  gas: await publicClient.estimateGas({ account, to: FACTORY_ADDRESS, data }),
  maxFeePerGas: fees.maxFeePerGas,
  maxPriorityFeePerGas: fees.maxPriorityFeePerGas,
};
const signedTx = await walletClient.signTransaction(tx);
const txHash = keccak256(signedTx);

// 4. Submit metadata BEFORE broadcasting (must be immediately followed by step 5)
const form = new FormData();
form.append("txHash", txHash);
form.append("name", name);
form.append("symbol", symbol);
form.append("chainId", String(mainnet.id));
form.append("description", "An example token");
// Socials: JSON array of up to 5 http(s) URLs. The icon is derived from each
// URL; invalid entries are dropped server-side.
form.append("socials", JSON.stringify([
  "https://x.com/yourproject",
  "https://t.me/yourproject",
]));
// form.append("image", imageFile); // optional File / Blob
const metaRes = await fetch(`${API_BASE}/api/tokens/create`, {
  method: "POST",
  headers: { Authorization: `Bearer ${jwt}` },
  body: form,
});
if (!metaRes.ok) throw new Error(`metadata POST failed: ${await metaRes.text()}`);

// 5. Broadcast immediately — no delay allowed between steps 4 and 5
const broadcastedHash = await publicClient.sendRawTransaction({
  serializedTransaction: signedTx,
});
console.log("token tx:", broadcastedHash); // === txHash