Developer API

npm install viem

# Keep private keys out of source control.
CREATOR_PRIVATE_KEY=0x...
# 56 = BNB Smart Chain. Every read and draft below is scoped to this chain.
CHAIN_ID=56
# Any BNB Smart Chain RPC.
RPC_URL=https://bsc-dataseed.bnbchain.org
IMAGE_URI=ipfs://...
METADATA_URI=ipfs://...
METADATA_HASH=0x...

import {
  createPublicClient,
  createWalletClient,
  decodeFunctionData,
  defineChain,
  http,
  isHex,
  keccak256,
  parseUnits,
  size,
  toHex,
  zeroAddress,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";

const API_BASE = "https://www.jibe.trade/api/public/v1";
const CHAIN_ID = Number(process.env.CHAIN_ID ?? 56);
const rpcUrl = process.env.RPC_URL;
const privateKey = process.env.CREATOR_PRIVATE_KEY;
if (!rpcUrl || !privateKey || !isHex(privateKey) || size(privateKey) !== 32) {
  throw new Error("Missing RPC URL or valid 32-byte signer");
}

const account = privateKeyToAccount(privateKey);

// Every endpoint is scoped by chainId (56 when omitted). Sending it on every
// call keeps reads, drafts, and vault actions on one chain.
async function api(path, init) {
  const url = new URL(`${API_BASE}${path}`);
  url.searchParams.set("chainId", String(CHAIN_ID));
  const response = await fetch(url, init);
  const payload = response.headers.get("content-type")?.includes("application/json")
    ? await response.json()
    : null;
  if (!response.ok) {
    if (response.status === 429) {
      throw new Error(
        `Rate limited; retry after ${response.headers.get("retry-after") ?? "a short delay"} seconds`,
      );
    }
    throw new Error(
      payload?.error
        ? `${payload.error.code}: ${payload.error.message}`
        : `API request failed with status ${response.status}`,
    );
  }
  if (!payload || !("data" in payload)) throw new Error("Invalid API response");
  return payload.data;
}

const [config, marketCatalog] = await Promise.all([
  api("/config"),
  api("/markets"),
]);
if (config.chain.id !== CHAIN_ID) throw new Error("Config is for another chain");
if (!config.capability.canPrepare) {
  throw new Error(config.capability.blocker ?? "Launching is unavailable");
}

// config.chain describes the chain the API answered for: id, name, native
// currency (BNB), and explorer. Build the viem chain from it instead of
// hardcoding one.
const chain = defineChain({
  id: config.chain.id,
  name: config.chain.name,
  nativeCurrency: config.chain.nativeCurrency,
  rpcUrls: { default: { http: [rpcUrl] } },
  blockExplorers: {
    default: { name: "Explorer", url: config.chain.explorerUrl },
  },
});
const wallet = createWalletClient({ account, chain, transport: http(rpcUrl) });
const publicClient = createPublicClient({ chain, transport: http(rpcUrl) });

const strategyMarkets = marketCatalog.strategyMarkets.filter(
  (market) => market.verified,
);
const nativeQuote = marketCatalog.quoteAssets.find(
  (quote) => quote.selectable && quote.address.toLowerCase() === zeroAddress,
);
if (!nativeQuote || strategyMarkets.length === 0) {
  throw new Error("No selectable native quote or strategy market");
}

const primaryMarket = strategyMarkets[0];
const nativeFixedLaunch = {
  // The chain the draft targets; must match the chain /config and /markets
  // were read from. Defaults to 56 (BNB Smart Chain) when omitted.
  chainId: CHAIN_ID,

  // Wallet that must sign the prepared launch transaction.
  creator: account.address,

  // Token identity. Public launches require canonical ipfs:// URIs.
  name: "Example Jibe",
  symbol: "EXPERP",
  description: "A token with a managed perpetual strategy.",
  imageUri: process.env.IMAGE_URI,
  metadataUri: process.env.METADATA_URI,
  metadataHash: process.env.METADATA_HASH,
  website: "",
  twitter: "",
  telegram: "",
  github: "",
  youtube: "",
  debox: "",
  venue: "flap",

  // Read launchable quote details from /markets; never hardcode decimals.
  quoteAsset: nativeQuote.address,
  quoteSymbol: nativeQuote.symbol,
  quoteDecimals: nativeQuote.decimals,

  // Maximum opening purchase in raw quote units. "0" disables it.
  creatorBuyMode: "quote",
  initialBuyAmount: "0",

  // Trading tax in basis points: 100 BPS = 1%.
  buyTaxBps: 100,
  sellTaxBps: 100,

  // Creator weights over the post-protocol remainder must total 10,000 BPS.
  vaultBps: 10000,
  dividendBps: 0,
  deflationBps: 0,
  lpBps: 0,

  // Seconds. The website default is 30 days.
  antiFarmerDurationSeconds: 30 * 86400,

  // Zero allocates all returned USDT classified as strategy profit to the
  // buyback bucket. A keeper later executes the purchase and dead-address transfer.
  profitDividendBps: 0,

  // Quote dividends use the selected launch-pair asset.
  dividendMode: "quote",
  dividendAsset: nativeQuote.address,

  // Fixed mode has no DAO vote or delegated manager.
  strategyMode: "fixed",
  strategyLegs: [{
    // IDs and limits come from /markets.
    marketId: primaryMarket.marketId,
    marketLabel: primaryMarket.label,
    direction: "long",
    // 10,000 BPS = 100% of strategy equity.
    equityAllocationBps: 10000,
    // 20,000 BPS = 2x, capped by the live market limit.
    requestedLeverageBps: Math.min(
      20000,
      primaryMarket.maximumLeverageBps,
    ),
  }],
};

const prepared = await api("/launches/prepare", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "idempotency-key": crypto.randomUUID(),
  },
  body: JSON.stringify({ launch: nativeFixedLaunch }),
});

console.log(prepared.launchId);
console.log(prepared.predictedToken);
console.log(prepared.launchTransaction);

const erc20Quote = marketCatalog.quoteAssets.find(
  (quote) => quote.selectable && quote.address.toLowerCase() !== zeroAddress,
);
const [first, second, third] = strategyMarkets;
if (
  !erc20Quote ||
  config.limits.strategyLegLimit < 3 ||
  !first ||
  !second ||
  !third
) {
  throw new Error("This example requires an ERC-20 quote and three markets");
}

const erc20MultiMarketLaunch = {
  ...nativeFixedLaunch,
  name: "Multi Market Index",
  symbol: "MMARK",

  // Switch the launch pair from BNB to a selectable ERC-20.
  quoteAsset: erc20Quote.address,
  quoteSymbol: erc20Quote.symbol,
  quoteDecimals: erc20Quote.decimals,

  // Convert a 100-token opening purchase to raw ERC-20 units.
  initialBuyAmount: parseUnits("100", erc20Quote.decimals).toString(),
  dividendAsset: erc20Quote.address,

  // Distinct markets whose allocations total 10,000 BPS.
  strategyLegs: [
    {
      marketId: first.marketId,
      marketLabel: first.label,
      direction: "long",
      equityAllocationBps: 4000,
      requestedLeverageBps: Math.min(20000, first.maximumLeverageBps),
    },
    {
      marketId: second.marketId,
      marketLabel: second.label,
      direction: "short",
      equityAllocationBps: 3500,
      requestedLeverageBps: Math.min(15000, second.maximumLeverageBps),
    },
    {
      marketId: third.marketId,
      marketLabel: third.label,
      direction: "long",
      equityAllocationBps: 2500,
      requestedLeverageBps: Math.min(15000, third.maximumLeverageBps),
    },
  ],
};

const preparedErc20 = await api("/launches/prepare", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "idempotency-key": crypto.randomUUID(),
  },
  body: JSON.stringify({ launch: erc20MultiMarketLaunch }),
});

// DAO: token stakers propose and vote on replacement portfolios.
const daoLaunch = {
  ...erc20MultiMarketLaunch,
  name: "Holder Governed Markets",
  symbol: "HGOV",
  strategyMode: "dao",
  governanceSettings: {
    // Duration is canonical seconds (12 hours here); the launch UI accepts
    // minute, hour, or day input.
    votingPeriodSeconds: 43200,
    // A proposer needs 0.001% of the snapshotted token totalSupply().
    proposalThresholdPpm: 10,
    // At least 10% of the snapshotted token totalSupply() must participate.
    quorumPpm: 100000,
    // At least 60% of Support-plus-Oppose votes must be Support.
    approvalBps: 6000,
  },
};

// Delegated: the nonzero manager becomes the master authority.
const delegatedLaunch = {
  ...nativeFixedLaunch,
  name: "Delegated Strategy",
  symbol: "DSTRAT",
  strategyMode: "delegated",
  // The master can update the strategy, appoint multiple delegates, and transfer
  // master authority. Appointed delegates can also update the portfolio.
  strategyManager: "0x1111111111111111111111111111111111111111",
};

// Prepare either object using:
// body: JSON.stringify({ launch: daoLaunch })
// body: JSON.stringify({ launch: delegatedLaunch })

const token = "0x..."; // Canonical launched token address.

const vaultState = await api(
  `/tokens/${token}/vault?actor=${account.address}`,
);
if (vaultState.actor?.address.toLowerCase() !== account.address.toLowerCase()) {
  throw new Error("actor must equal the signing wallet");
}
console.log(vaultState.mode, vaultState.profile, vaultState.portfolio);
console.log(vaultState.delegated, vaultState.dao, vaultState.actor);

// Reads remain available even when action preparation is unavailable.
if (!vaultState.capability.canPrepareActions) {
  console.log(vaultState.capability.actionBlocker);
}

async function prepareVaultAction(token, input) {
  if (input.actor.toLowerCase() !== account.address.toLowerCase()) {
    throw new Error("actor must equal the signing wallet");
  }
  const currentConfig = await api("/config");
  if (!currentConfig.capability.vaultManagement.canPrepareActions) {
    throw new Error(
      currentConfig.capability.vaultManagement.blocker?.message ??
      "Vault management is unavailable",
    );
  }
  return api(`/tokens/${token}/vault/actions/prepare`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(input),
  });
}

async function broadcastPreparedAction(preparedAction) {
  // The API returns target, calldata, chain, and value. Never replace them.
  // Preparation is stateless/advisory; the contract revalidates current state.
  const { transaction } = preparedAction;
  const hash = await wallet.sendTransaction({
    account,
    chain,
    to: transaction.to,
    data: transaction.data,
    value: BigInt(transaction.value),
  });
  const receipt = await publicClient.waitForTransactionReceipt({ hash });
  if (receipt.status !== "success") throw new Error("Vault action reverted");
  return { hash, receipt };
}

// No private key, signed transaction, target, or calldata is sent to the API.
// Only the locally controlled account signs and broadcasts.
const preparedAction = await prepareVaultAction(token, {
  action: "claim_rewards",
  actor: account.address,
});
await broadcastPreparedAction(preparedAction);

const delegatedState = await api(
  `/tokens/${token}/vault?actor=${account.address}`,
);
if (delegatedState.mode !== "delegated") throw new Error("Not delegated");
if (!delegatedState.actor?.authorized) throw new Error("Not authorized");

// Source IDs and leverage limits from /markets and leg capacity from vault state.
const market = marketCatalog.strategyMarkets[0];
if (!market || (delegatedState.limits?.strategyLegLimit ?? 0) < 1) {
  throw new Error("No supported strategy market");
}
const replacement = await prepareVaultAction(token, {
  action: "replace_portfolio",
  actor: account.address,
  active: true,
  portfolio: [{
    marketId: market.marketId,
    direction: "long",
    equityAllocationBps: 10000,
    requestedLeverageBps: Math.min(20000, market.maximumLeverageBps),
  }],
});

// The API reads and binds the current profile version; clients do not supply it.
if (replacement.expectedProfileVersion !== delegatedState.profile?.version) {
  throw new Error("State changed; request a fresh preparation");
}
await broadcastPreparedAction(replacement);

const delegate = "0x...";
const secondDelegate = "0x...";
const nextMaster = "0x...";

// The API checks the current actor role before every stateless preparation.
for (const input of [
  {
    action: "add_delegates",
    actor: account.address,
    delegates: [delegate, secondDelegate],
  },
  { action: "remove_delegate", actor: account.address, delegate },
  { action: "clear_delegates", actor: account.address },
]) {
  await broadcastPreparedAction(await prepareVaultAction(token, input));
}

// Only the current delegated master may transfer master authority.
await broadcastPreparedAction(await prepareVaultAction(token, {
  action: "transfer_manager",
  actor: account.address,
  newManager: nextMaster,
}));

const amount = "1000000000000000000"; // Raw token units chosen by the user.
const daoState = await api(
  `/tokens/${token}/vault?actor=${account.address}`,
);
if (daoState.mode !== "dao" || !daoState.contracts.stakeVault) {
  throw new Error("Not a DAO vault");
}

// Approval target and amount are encoded server-side from canonical state.
const approval = await prepareVaultAction(token, {
  action: "approve_stake",
  actor: account.address,
  amount,
});
await broadcastPreparedAction(approval);

// Refresh state after approval; preparation checks the observed allowance.
const stake = await prepareVaultAction(token, {
  action: "stake",
  actor: account.address,
  amount,
});
await broadcastPreparedAction(stake);

let latestDaoState = await api(
  `/tokens/${token}/vault?actor=${account.address}`,
);
const claimableRewards = BigInt(
  latestDaoState.actor?.stake?.claimableRewards ?? "0",
);

// Claim is a separate action. Simulate before broadcasting because pending
// reward sources can change between reads.
if (claimableRewards > 0n) {
  const claim = await prepareVaultAction(token, {
    action: "claim_rewards",
    actor: account.address,
  });
  await publicClient.call({
    account: account.address,
    to: claim.transaction.to,
    data: claim.transaction.data,
    value: BigInt(claim.transaction.value),
  });
  await broadcastPreparedAction(claim);
}

latestDaoState = await api(
  `/tokens/${token}/vault?actor=${account.address}`,
);
const withdrawAmount = latestDaoState.actor?.stake?.amount;
if (!withdrawAmount || withdrawAmount === "0") throw new Error("No stake");

// withdraw() also attempts to deliver accrued rewards. Do not automatically
// send a second claim afterward; a zero-value claim reverts with InvalidAmount.
await broadcastPreparedAction(await prepareVaultAction(token, {
  action: "withdraw_stake",
  actor: account.address,
  amount: withdrawAmount,
}));

const current = await api(
  `/tokens/${token}/vault?actor=${account.address}`,
);
const proposalMarket = marketCatalog.strategyMarkets[0];
const title = "Increase primary market exposure";
const body =
  "Increase primary market exposure while retaining the configured safeguards.";
if (
  current.mode !== "dao" ||
  !proposalMarket ||
  (current.limits?.strategyLegLimit ?? 0) < 1
) throw new Error("DAO proposal is unavailable");

const proposal = await prepareVaultAction(token, {
  action: "propose_portfolio",
  actor: account.address,
  active: true,
  title,
  body,
  portfolio: [{
    marketId: proposalMarket.marketId,
    direction: "long",
    equityAllocationBps: 10000,
    requestedLeverageBps: Math.min(
      20000,
      proposalMarket.maximumLeverageBps,
    ),
  }],
});
// Current version and proposal fee are derived from the same API state.
if (
  proposal.expectedProfileVersion !== current.profile?.version ||
  proposal.transaction.value !== current.dao?.proposalFeeWei
) throw new Error("Proposal state changed; prepare again");

await broadcastPreparedAction(proposal);

const votingState = await api(
  `/tokens/${token}/vault?actor=${account.address}`,
);
const activeProposalId = votingState.dao?.activeProposals.find(
  (proposal) => proposal.state === 1,
)?.id;
if (!activeProposalId) throw new Error("No active proposal");
if (BigInt(votingState.actor?.stake?.votes ?? "0") === 0n) {
  throw new Error("No current voting weight");
}

await broadcastPreparedAction(await prepareVaultAction(token, {
  action: "cast_vote",
  actor: account.address,
  proposalId: activeProposalId,
  choice: "support",
}));

// Refresh state after voting closes.
const executableState = await api(
  `/tokens/${token}/vault?actor=${account.address}`,
);
const active = executableState.dao?.activeProposals.find(
  (proposal) =>
    proposal.state === 3 &&
    proposal.isSelectedWinner &&
    BigInt(executableState.observedBlock.timestamp) >=
      BigInt(proposal.executeAfter),
);
if (!active) throw new Error("No selected proposal is ready for execution");

const execution = await prepareVaultAction(token, {
  action: "execute_proposal",
  actor: account.address,
  proposalId: active.id,
});

// Simulate against current state in case conditions changed after the API read.
await publicClient.call({
  account: account.address,
  to: execution.transaction.to,
  data: execution.transaction.data,
  value: BigInt(execution.transaction.value),
});
await broadcastPreparedAction(execution);

import { readFile } from "node:fs/promises";
import { keccak256, toHex } from "viem";

function canonicalJson(value) {
  if (Array.isArray(value)) {
    return `[${value.map(canonicalJson).join(",")}]`;
  }
  if (value && typeof value === "object") {
    return `{${Object.entries(value)
      .sort(([left], [right]) => left.localeCompare(right))
      .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
      .join(",")}}`;
  }
  return JSON.stringify(value);
}

const metadata = {
  name: "Example Jibe",
  symbol: "EXPERP",
  description: "A token with a managed perpetual strategy.",
  links: {
    website: "", twitter: "", telegram: "",
    github: "", youtube: "", debox: "",
  },
};
const imageBytes = new Uint8Array(await readFile("./token.png"));
const idempotencyKey = crypto.randomUUID();

// Optional: bind the upload to your wallet. Skip the signature and the three
// x-wallet-*/x-signature-* headers below to upload with the key alone.
const expiresAt = new Date(Date.now() + 4 * 60_000).toISOString();
const imageHash = keccak256(toHex(imageBytes));
const metadataInputHash = keccak256(
  toHex(new TextEncoder().encode(canonicalJson(metadata))),
);
const signature = await account.signTypedData({
  domain: {
    name: "Jibe Public API",
    version: "1",
    chainId: CHAIN_ID,
  },
  types: {
    MetadataUpload: [
      { name: "wallet", type: "address" },
      { name: "chainId", type: "uint256" },
      { name: "audience", type: "string" },
      { name: "expiresAt", type: "uint64" },
      { name: "imageHash", type: "bytes32" },
      { name: "metadataHash", type: "bytes32" },
      { name: "nonceHash", type: "bytes32" },
    ],
  },
  primaryType: "MetadataUpload",
  message: {
    wallet: account.address,
    chainId: BigInt(CHAIN_ID),
    audience: API_BASE,
    expiresAt: BigInt(Math.floor(new Date(expiresAt).getTime() / 1000)),
    imageHash,
    metadataHash: metadataInputHash,
    nonceHash: keccak256(toHex(idempotencyKey)),
  },
});

const form = new FormData();
form.set("image", new File([imageBytes], "token.png", { type: "image/png" }));
form.set("metadata", JSON.stringify(metadata));
const response = await fetch(`${API_BASE}/metadata`, {
  method: "POST",
  headers: {
    "idempotency-key": idempotencyKey,
    "x-chain-id": String(CHAIN_ID),
    "x-wallet-address": account.address,
    "x-wallet-signature": signature,
    "x-signature-expires-at": expiresAt,
  },
  body: form,
});
const payload = await response.json();
if (!response.ok) throw new Error(payload.error?.message);

const { imageUri, metadataUri, metadataHash } = payload.data;

async function executePreparedLaunch(preparation) {
  const latest = await api("/config");
  if (!latest.capability.canLaunch) {
    throw new Error(latest.capability.blocker ?? "Launching is unavailable");
  }

  // ERC-20 creator purchases return an exact approval.
  if (preparation.approvalTransaction) {
    const approval = preparation.approvalTransaction;
    const approvalHash = await wallet.sendTransaction({
      account,
      chain,
      to: approval.to,
      data: approval.data,
      value: BigInt(approval.value),
    });
    const receipt = await publicClient.waitForTransactionReceipt({
      hash: approvalHash,
    });
    if (receipt.status !== "success") throw new Error("Approval reverted");
  }

  const transaction = preparation.launchTransaction;
  const launchHash = await wallet.sendTransaction({
    account,
    chain,
    to: transaction.to,
    data: transaction.data,
    value: BigInt(transaction.value),
  });
  const launchReceipt = await publicClient.waitForTransactionReceipt({
    hash: launchHash,
    timeout: 10 * 60_000,
  });
  if (launchReceipt.status !== "success") {
    throw new Error("Launch transaction reverted");
  }
  // The launch is complete. The token lives at preparation.predictedToken.
  console.log("Launch succeeded:", preparation.predictedToken, launchHash);
  return launchHash;
}

await executePreparedLaunch(prepared);

const transaction = prepared.launchTransaction;
const latest = await api("/config");
if (!latest.capability.canLaunch || !latest.capability.canRelay) {
  throw new Error(latest.capability.blocker ?? "Relay is unavailable");
}

// Populate nonce, gas, and EIP-1559 fees before signing raw bytes.
const transactionRequest = await wallet.prepareTransactionRequest({
  account,
  chain,
  to: transaction.to,
  data: transaction.data,
  value: BigInt(transaction.value),
});
const serializedTransaction = await wallet.signTransaction(transactionRequest);

const relay = await api("/launches/submit", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    launchId: prepared.launchId,
    serializedTransaction,
  }),
});
console.log(relay.transactionHash, relay.relayState);

// Optional: wait until the token page and API data are ready.
async function waitForIndexedLaunch(launchId) {
  for (;;) {
    const status = await api(`/launches/${launchId}`);
    console.log(status.state);

    if (status.state === "indexed" || status.state === "finalized") {
      return status;
    }
    if (["failed", "expired", "reorged"].includes(status.state)) {
      throw new Error(status.message ?? status.state);
    }
    await new Promise((resolve) =>
      setTimeout(resolve, status.retryAfterMs ?? 2000),
    );
  }
}

const launch = await waitForIndexedLaunch(prepared.launchId);
console.log(launch.token, launch.path);

const coordinatorAbi = await api("/abi/coordinator.json");
const decoded = decodeFunctionData({
  abi: coordinatorAbi,
  data: prepared.launchTransaction.data,
});
if (decoded.functionName !== "launch") {
  throw new Error("Unexpected prepared coordinator call");
}
console.log(
  `${config.chain.explorerUrl}/address/${config.coordinator}?tab=contract`,
);