Module 07 — Token Creation

Create and manage tokens on the BASIS factory. Earn permanent 20% of net trading fees on every token you deploy.

Prerequisites

• Wallet funded with USDB (→01), client initialized (→02)
• Understand hybrid multiplier and floor mechanics — this is your most important creation choice
• Optional: register an agent identity so your token attribution is on-chain

Next steps after creation

• Run a launch event? Activate surge tax (creator-only, time-decaying)
• Locking team allocations? Use vesting schedules to signal long-term commitment
• Building a prediction market? Use the prediction market flow instead — Predict+ tokens are created differently
• Want to compound your creator advantage? Read Module 12 Strategy 4: Creator's Edge
• Find your token in your portfolio: getTokensByCreator()

Why Create a Token

Creating a token makes you a revenue-generating business on the platform, not just a trader.

What you get as creator:

• Permanent 20% of net trading fees — on every buy and sell, by any user, forever. No action required after creation. (= 0.1% of Stable+ trade volume, 0.3% of Floor+ trade volume)
• Reward phase control — set a volume threshold where early buyers earn reward shares. Buy it up yourself to capture them, or share it with your community.
• Surge tax authority — activate time-decaying extra fees during launch events. All surge basis points go to your dev portion.
• Stacking foundation — your token is collateral-eligible. Buy your own token → borrow USDB → deploy elsewhere (see Strategy 4: Creator's Edge).
• Earns airdrop points — one-time at creation, ongoing from your token's volume.

If your token does $10,000 in daily volume, you earn a cut of that every day without further action. Volume compounds. Fees compound. The creator role is structural.

How It Works

Factory contract → creates the token → sets you as permanent dev → token trades on the DEX immediately.

Two-phase lifecycle:

1. Reward phase (optional) — set by usdbForBonding. Lasts until cumulative trading volume hits your threshold. Early buyers earn reward shares claimable via claimRewards(). Once the volume threshold is hit, hasBonded flips to true and the reward phase ends permanently. Max threshold: 150,000 USDB.

2. Standard AMM — all trading continues on the AMM. Creator fees (20%) keep flowing forever.

Pitfall: Do not ignore the reward phase on newly launched tokens you want to buy. Reward phase buys earn bonus airdrop points and better pricing. Once the threshold is hit, that window closes permanently — it never reopens.

Frozen launch — optionally start trading locked. Only whitelisted wallets can buy until you call disableFreeze(). Useful for presales, controlled early access, or OTC allocation before public launch.

Actions

Create Token

Method: client.factory.createTokenWithMetadata(options)

Recommended over bare createToken. Handles image upload to IPFS via Pinata and metadata registration in one call. Token symbols must be CAPITALISED.

JavaScript:

const { BasisClient } = require("basis-sdk-js");

const client = await BasisClient.create({ privateKey: "0xYourPrivateKey..." });

const result = await client.factory.createTokenWithMetadata({
  symbol: "MYTKN",
  name: "My Awesome Token",
  hybridMultiplier: 50n,
  startLP: 1000n,
  description: "My awesome DeFi token on Basis",
  imageUrl: "https://example.com/my-logo.png",
  website: "https://myproject.com",
});

console.log("Token:", result.tokenAddress);
console.log("Image:", result.imageUrl);
console.log("Metadata:", result.metadata.url);

Python:

from basis_sdk import BasisClient

client = BasisClient.create(private_key="0xYourPrivateKey...")

result = client.factory.create_token_with_metadata(
    symbol="MYTKN", name="My Awesome Token",
    hybrid_multiplier=50, start_lp=1000,
    description="My awesome DeFi token on Basis",
    image_url="https://example.com/my-logo.png",
    website="https://myproject.com",
)
print("Token:", result["token_address"])

Returns: { hash, receipt, tokenAddress, imageUrl, metadata }

Parameter Reference

Fee: Check getFeeAmount() before creating — currently 0 in Phase 1 but may change. Earns: One-time airdrop points. Requires: SIWE authentication (auto-handled by BasisClient.create — see Module 16).

Understanding startLP

startLP sets the price depth — how much capital is needed to move the price. It does not affect token type or the floor mechanism. Think of it as the zoom level on the price chart.

A $100 buy into a 1,000 LP token has the same percentage price impact as a $1,000 buy into a 10,000 LP token. Scaling LP up means more capital is required to create visible movement — which can signal credibility and attract larger trades at launch.

Manage Token (Post-Creation)

Disable Freeze

Opens a frozen token to public trading. Irreversible — once called, freeze cannot be re-enabled.

await client.factory.disableFreeze(tokenAddress);

Whitelist Wallets (frozen tokens)

Add wallets that can trade while the token is frozen. Each wallet gets a max buy cap.

await client.factory.setWhitelistedWallet(
  tokenAddress,
  ["0xWallet1...", "0xWallet2..."],
  maxUsdbPerWallet,  // bigint, 18 decimals
  "presale round 1"  // label/tag
);

Remove from Whitelist

await client.factory.removeWhitelist(tokenAddress, "0xWallet...");

Claim Creator Rewards

Claim your accumulated 20% dev fee share in USDB. Can be called at any time.

const { hash, receipt } = await client.factory.claimRewards(tokenAddress);

Note: claimRewards() also claims reward-phase buyer rewards for addresses that participated in the reward phase. The creator's 20% dev fee and early-buyer reward shares are both claimable through this method.

Configure Taxes

Tax rates are set on creation and adjustable after. The dev rate and buyback rate operate on the tax portion of the trade, not the total trade value.

Limits:

• Dev tax rate: 15–40% (of the tax portion)
• Buyback rate: 0–20% (of the tax portion)

Read methods:

// Effective tax rate for a specific user on a specific token (basis points)
const rate = await client.taxes.getTaxRate(tokenAddress, userAddress);

// Base rates for all token categories
const bases = await client.taxes.getBaseTaxRates();
// Returns: { stasis, stable, default, prediction } — each in basis points

// Current active surge tax rate (0 if none active)
const surge = await client.taxes.getCurrentSurgeTax(tokenAddress);

Surge Tax

A time-decaying extra fee that creators activate manually. Used for launch day events and managing early sell pressure. All surge basis points go to the creator's dev portion.

Activate:

await client.taxes.startSurgeTax(
  startRate,   // bigint, basis points (e.g., 500n = 5%)
  endRate,     // bigint, basis points (can be 0)
  duration,    // bigint, seconds (minimum 3600)
  tokenAddress
);

The tax decays linearly from startRate to endRate over duration seconds.

Check remaining quota first:

const remainingSeconds = await client.taxes.getAvailableSurgeQuota(tokenAddress);
// 0 means quota exhausted — wait for older windows to roll off

Surge tax limits by token type:

Surge rules:

• startRate ≥ endRate
• Minimum duration: 3,600 seconds (1 hour)
• Quota: maximum 7 days of active surge per rolling 30-day window
• Only the token creator can start or end a surge
• Predict+ tokens cannot use surge tax

Tip: Surge tax is automatically reflected in getAmountsOut() trade previews. Always preview before executing — the preview includes active surge in the effective price calculation.

Read Methods

Reading hybridMultiplier on-chain:

const multiplier = await client.publicClient.readContract({
  address: tokenAddress,
  abi: [{"inputs":[],"name":"hybridMultiplier","outputs":[{"name":"","type":"uint256"}],"stateMutability":"view","type":"function"}],
  functionName: 'hybridMultiplier',
});
// 100n = Stable+ or Predict+, 1-90 = Floor+

Choosing Your Token Type

The most important decision at creation. Pick the wrong type and your mechanics work against your goals.

Do not use values 91–99. They are technically valid but disallowed by convention — there is no meaningful difference between a 91 Floor+ and a Stable+. Use 1–90 for Floor+ or exactly 100 for Stable+.

Stable+ — The Utility Token

Best when users repeatedly buy to use something, then the agent/service sells back to USDB. The ratchet mechanic (all slippage retained, price never drops) rewards high transaction frequency.

Use when: Services, subscriptions, API access, pay-per-use tools.
Avoid when: Speculative tokens — there's no exciting price discovery to attract traders.

Floor+ — The Community Token

Best for projects where holders need confidence against dumps. The floor rises on every buy-sell cycle. Whale dumps create dips that look like buying opportunities rather than death spirals.

Use when: Communities, brand tokens, fan tokens, loyalty programs.
Key window: Near launch, the gap between spot and floor is smallest — highest leverage ratio, lowest buyer risk, strongest structural buy signal. Market your launch to coincide with this window.

Predict+ — The Engagement Token

Created as part of a prediction market. The token earns from all market trading volume. Surge tax is disabled for Predict+ tokens.

Use when: Monetising domain expertise, running information markets, driving engagement around predictions. See Module 13 for full creator strategy.

Fees

The 20% creator fee is calculated on the net fee portion of every trade. It accrues automatically and is claimed via claimRewards().

Errors

For the full alphabetical error index across all modules, see Module 18 — SDK Reference.

What Next

After creating a token, the typical creator flow:

1. If frozen: Call setWhitelistedWallet() for presale participants, then disableFreeze() when ready for public trading.
2. Activate surge tax for launch day to manage early sell pressure and boost creator fees. Check getAvailableSurgeQuota() first.
3. Buy your own token during the reward phase to earn reward shares — or configure usdbForBonding low enough that you capture most of it yourself.
4. Monitor state with getTokenState() — watch hasBonded to know when the reward phase has ended.
5. Claim accumulated fees regularly with claimRewards().
6. Stack on top — Creator's Edge strategy: buy your own Floor+/Predict+ token → borrow USDB → deploy across Stable+, lending, and predictions. You earn 20% creator fees from other users' volume on top of your stacked positions. See Module 12 for the full stacking strategies module.

See Also

• Module 04 — Trading: Understand how your token will trade and how creator fees route
• Module 05 — Lending: Borrow against your own token (Creator's Edge stack)
• Module 08 — Predictions: Create a Predict+ market token instead — different flow, similar economics
• Module 09 — Vesting: Lock team/investor allocations on a schedule
• Module 11 — Token Mechanics: Hybrid multiplier formula, floor math, surge tax, reward phase internals
• Module 12 — Strategy & Stacking: Creator's Edge — stack creator fees on top of borrow/lend/leverage paths
• Module 18 — SDK Reference: Full client.factory and client.taxes method signatures