API

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

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

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

function createToken(
    DirectTokenSetup                setup,
    DirectPair[]                    pairs,
    TaxConfigsWithDirectAllocation  taxAllocationConfigs,
    AntiSniperConfigs               antiSniperConfigs,
    CreatorVault[]                  creatorVaults,
    DevBuy                          devBuy,
    address                         referral
) payable returns (address token);

struct DirectTokenSetup {
    string     name;
    string     symbol;
    bytes32    salt;              // any value; namespaced by msg.sender (see Salt)
    FeeShare[] feeShares;         // shares sum to 10000
    bool       renounceOwnership; // true: deployed ownerless; false: owner = msg.sender
    uint16     lpFeeBps;          // 100 (1%) or 50 (0.5%), else InvalidLpFeeBps
}

struct DirectPair {
    address quote;        // address(0) for the chain's native coin, else a whitelisted ERC20
    uint16  weightBps;    // this pool's share of the circulating supply
}

struct DevBuy {
    uint8         pairIndex;    // which pool the buy runs on
    PoolKey[]     route;        // MUST be empty - the factory derives the route from the whitelist
    uint256       minQuoteOut;  // floor on the in-launch conversion; 0 to disable
    uint256       quoteAmount;  // raw quote the factory pulls from the caller
    SupplyShare[] recipients;   // who receives the bought tokens; shares sum to 10000
}

struct TaxConfigsWithDirectAllocation {
    uint16 buyTaxBps;
    uint16 sellTaxBps;
    uint32 taxDurationSeconds;
    bool   startTaxFromLaunch;
    uint16 buyTaxDecayStartBps;
    uint16 sellTaxDecayStartBps;
    uint32 taxDecayDuration;
    EarningsAllocationMultiConfig earningsAllocation;
    bytes[] quoteRoutes;   // positional to `pairs`: each quote's native->quote V4 route, needed
                           // only where a dividends leg must leave that quote; "0x" otherwise,
                           // trailing empties may be omitted. InvalidQuoteRoutes if malformed.
}

struct EarningsAllocationMultiConfig {
    uint16    burnBps;
    uint16    dividendsBps;
    uint16    liquidityBps;
    address[] dividendTokens;
    uint16[]  dividendWeightsBps;
    bytes[]   dividendRoutes;
}

pool's quote  | paid with                      | quoteAmount | minQuoteOut | msg.value
--------------|--------------------------------|-------------|-------------|-------------------
native (0x0)  | msg.value                      | 0           | 0           | amount to spend
ERC20         | the quote, pulled by the factory | raw amount  | 0           | 0
ERC20         | native, converted in-launch    | 0           | conversion floor | ETH to convert

function LAUNCH_MARKET_CAP_X18() view returns (uint256);   // 1.125e18: the opening market cap
                                                           // of EVERY pair, native-denominated
function previewLaunchTick(address quote)
    view returns (int24 tick, uint256 priceX18, uint256 marketCapX18);

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

struct SupplyShare {
    address account;
    uint256 shares;   // bps, > 0; array sums to exactly 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 { toHex } from "viem";

const salt = toHex(crypto.getRandomValues(new Uint8Array(32)));

import { keccak256, encodeFunctionData } from "viem";

// setup, pairs, taxAllocationConfigs, antiSniperConfigs, devBuy and value built as in Step 2;
// salt from the Salt section.
const data = encodeFunctionData({
  abi: factoryAbi,
  functionName: "createToken",
  args: [setup, pairs, taxAllocationConfigs, antiSniperConfigs, creatorVaults, devBuy, referral],
});

const fees = await publicClient.estimateFeesPerGas();
const tx = {
  type: "eip1559",
  chainId,
  nonce: await publicClient.getTransactionCount({ address: account.address }),
  to: factoryAddress,
  data,
  value, // 0n unless the dev buy is paid in native (see Funding the dev buy)
  gas: await publicClient.estimateGas({ account, to: factoryAddress, data, value }),
  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
)

npm i viem
PRIVATE_KEY=0x... node create-token-v4.mjs

// Create a token on Realm through RealmFactoryUniV4Direct (Uniswap V4, no bonding curve).
// Setup: `npm i viem`, then `PRIVATE_KEY=0x... node create-token-v4.mjs`.
// Runs on Robinhood testnet by default; set NETWORK = "mainnet" once it works there.
import {
  createPublicClient, createWalletClient, http, parseAbi, parseEventLogs,
  encodeFunctionData, keccak256, toHex, zeroAddress,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { readFile } from "node:fs/promises";
import { basename } from "node:path";

const NETWORK = "testnet";
const NETWORKS = {
  mainnet: {
    chainId: 4663,
    rpc: "https://rpc.mainnet.chain.robinhood.com",
    api: "https://realm.trade",
    factory: "0xC763b1795DaBe2D2336EbA214d16969EBc5db27F",
  },
  testnet: {
    chainId: 46630,
    rpc: "https://rpc.testnet.chain.robinhood.com",
    api: "https://realm-rh-dev.vercel.app",
    factory: "0xF0399F67e359c08A18816E466364797b7fBc4df4",
  },
};
const net = NETWORKS[NETWORK];

// ---- Token config: tweak here ----
const NAME = "My Token";
const SYMBOL = "MTK";
const DESCRIPTION = "Launched through the Realm API";
const SOCIALS = ["https://x.com/yourproject"];
const IMAGE_FILE = ""; // optional local image (jpeg/png/gif/webp, <= 5MB), uploaded with the metadata
const IMAGE_URL = ""; // or an already-pinned IPFS url (ipfs://<cid>), faster than uploading
const DEV_BUY_ETH = 0n; // wei of ETH to buy at launch on the native pool; 0n = no dev buy

const factoryAbi = parseAbi([
  "struct FeeShare { address account; uint256 shares; bool directFeesEnabled; }",
  "struct DirectTokenSetup { string name; string symbol; bytes32 salt; FeeShare[] feeShares; bool renounceOwnership; uint16 lpFeeBps; }",
  "struct DirectPair { address quote; uint16 weightBps; }",
  "struct EarningsAllocationMultiConfig { uint16 burnBps; uint16 dividendsBps; uint16 liquidityBps; address[] dividendTokens; uint16[] dividendWeightsBps; bytes[] dividendRoutes; }",
  "struct TaxConfigsWithDirectAllocation { uint16 buyTaxBps; uint16 sellTaxBps; uint32 taxDurationSeconds; bool startTaxFromLaunch; uint16 buyTaxDecayStartBps; uint16 sellTaxDecayStartBps; uint32 taxDecayDuration; EarningsAllocationMultiConfig earningsAllocation; bytes[] quoteRoutes; }",
  "struct AntiSniperConfigs { uint16 maxBuyPerTxBps; uint16 maxWalletBps; uint40 protectionWindowSeconds; address[] whitelist; }",
  "struct CreatorVault { address owner; uint256 supplyBps; uint256 cliffSeconds; uint256 vestingSeconds; }",
  "struct PoolKey { address currency0; address currency1; uint24 fee; int24 tickSpacing; address hooks; }",
  "struct SupplyShare { address account; uint256 shares; }",
  "struct DevBuy { uint8 pairIndex; PoolKey[] route; uint256 minQuoteOut; uint256 quoteAmount; SupplyShare[] recipients; }",
  "function createToken(DirectTokenSetup setup, DirectPair[] pairs, TaxConfigsWithDirectAllocation taxAllocationConfigs, AntiSniperConfigs antiSniperConfigs, CreatorVault[] creatorVaults, DevBuy devBuy, address referral) payable returns (address)",
  "event TokenCreated(address indexed token, string name, string symbol, address tokenOwner, address launchpad, address graduator, address feeHandler)",
]);

const chain = {
  id: net.chainId,
  name: `Robinhood ${NETWORK}`,
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: { default: { http: [net.rpc] } },
};
const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const publicClient = createPublicClient({ chain, transport: http() });
const walletClient = createWalletClient({ account, chain, transport: http() });

// Single native (ETH) pool, 1% LP fee, no tax, no anti-sniper, no vaults.
const createArgs = (salt) => [
  {
    name: NAME,
    symbol: SYMBOL,
    salt,
    feeShares: [{ account: account.address, shares: 10000n, directFeesEnabled: false }],
    renounceOwnership: false,
    lpFeeBps: 100,
  },
  [{ quote: zeroAddress, weightBps: 10000 }],
  {
    buyTaxBps: 0, sellTaxBps: 0, taxDurationSeconds: 0, startTaxFromLaunch: false,
    buyTaxDecayStartBps: 0, sellTaxDecayStartBps: 0, taxDecayDuration: 0,
    earningsAllocation: {
      burnBps: 0, dividendsBps: 0, liquidityBps: 0,
      dividendTokens: [], dividendWeightsBps: [], dividendRoutes: [],
    },
    quoteRoutes: [],
  },
  { maxBuyPerTxBps: 0, maxWalletBps: 0, protectionWindowSeconds: 0, whitelist: [] },
  [],
  {
    pairIndex: 0, route: [], minQuoteOut: 0n, quoteAmount: 0n,
    recipients: DEV_BUY_ETH > 0n ? [{ account: account.address, shares: 10000n }] : [],
  },
  zeroAddress,
];

// 1. Authenticate
const message = `Sign in to Realm\nTimestamp: ${Date.now()}`;
const authRes = await fetch(`${net.api}/api/auth/wallet`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ address: account.address, signature: await walletClient.signMessage({ message }), message }),
});
const { token: jwt } = await authRes.json();
if (!jwt) throw new Error(`auth failed: ${authRes.status}`);

// 2. Any salt works; the factory namespaces it by sender (CREATE2 salt = keccak256(deployer ++ salt))
const salt = toHex(crypto.getRandomValues(new Uint8Array(32)));

// 3. Sign offline and precompute the txHash
const data = encodeFunctionData({ abi: factoryAbi, functionName: "createToken", args: createArgs(salt) });
const fees = await publicClient.estimateFeesPerGas();
const signedTx = await walletClient.signTransaction({
  type: "eip1559",
  chainId: chain.id,
  nonce: await publicClient.getTransactionCount({ address: account.address }),
  to: net.factory,
  data,
  value: DEV_BUY_ETH,
  gas: await publicClient.estimateGas({ account, to: net.factory, data, value: DEV_BUY_ETH }),
  maxFeePerGas: fees.maxFeePerGas,
  maxPriorityFeePerGas: fees.maxPriorityFeePerGas,
});
const txHash = keccak256(signedTx);

// 4. Submit metadata, keyed by the txHash...
const form = new FormData();
form.append("txHash", txHash);
form.append("name", NAME);
form.append("symbol", SYMBOL);
form.append("chainId", String(chain.id));
form.append("description", DESCRIPTION);
form.append("socials", JSON.stringify(SOCIALS));
if (IMAGE_FILE) {
  const type = `image/${IMAGE_FILE.split(".").pop().toLowerCase().replace("jpg", "jpeg")}`;
  form.append("image", new Blob([await readFile(IMAGE_FILE)], { type }), basename(IMAGE_FILE));
}
if (IMAGE_URL) form.append("imageUrl", IMAGE_URL);
const metaRes = await fetch(`${net.api}/api/tokens/create`, {
  method: "POST",
  headers: { Authorization: `Bearer ${jwt}` },
  body: form,
});
if (!metaRes.ok) throw new Error(`metadata POST failed: ${metaRes.status} ${await metaRes.text()}`);

// 5. ...and broadcast immediately after
await publicClient.sendRawTransaction({ serializedTransaction: signedTx });
const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
const [created] = parseEventLogs({ abi: factoryAbi, eventName: "TokenCreated", logs: receipt.logs });
console.log(`${receipt.status}: ${net.api}/token/${created.args.token.toLowerCase()}`);