Primary Offerings
A Primary Offering is the contract-governed first sale of new assets to investors, from funding through delivery, refunding only if the minimum is missed.
Primary Offerings is the issuer side of a token sale: one list of every sale across the organisation, and behind each entry the screen that funds it, activates it, pauses it, finalizes it, and settles what finalization decides. Each sale is a contract-governed first sale of newly issued tokens from the issuer to investors, at prices the issuer fixed per payment currency, not prices a market discovers. Two neighbouring jobs belong elsewhere. Trading is where a token with supply already in circulation changes hands afterward, at whatever price a resting order book gives, and a token can list there whether or not an offering ever sold it. Creating the token itself, its name, decimals, and compliance modules, happens earlier on the asset design side; an offering only ever sells a token that already exists.
The same sale shows two different screens depending on who opens it. The list under "Asset lifecycle" and the operating console behind it belong to accounts with an organisation-wide admin or token manager role; anyone else who follows a link to that console is sent back to the home screen. An investor meets the sale through its own subscription view instead: an overview with a "Subscribe" control, plus tabs for their own activity, pricing, investment, and documents. That investor view is scoped on the server, so a buyer only ever receives their own purchase rows. The operating console shows the whole raise, and it also shows your own vesting position read-only when the account operating the sale happens to hold one. The Primary OfferingA Primary Offering lets an issuer sell newly issued units once and resolve payment, allocation, and delivery or refunds as one on-chain outcome.Read the concept concept page explains the full sale and settlement model; this page is the Console surface for operating it.
Every offering walks the same one-way path. It starts in setup, where the issuer funds the sale contract and activates it. An optional presale admits whitelisted addresses under its own price and per-address cap. It then transitions to public sale under the standard price. Without a presale, eligible buyers start in the public phase. The issuer can pause it at any point. When its end arrives, what happens next turns on one number: whether total tokens sold reached the soft cap, the minimum the issuer configured for the raise to count as a success.
The sale moves through setup, then active, then ended, always in one direction. After the sale ends, send "Finalize Sale" to record the outcome. Meeting the soft cap, or having none, records success. Missing it opens per-currency refunds and delays the issuer's withdrawal for thirty days.
Setup ends the moment you activate
Everything that defines the sale is fixed when it is created, not on this screen. The creation wizard sets the token, the payment currencies, and the price in each currency. The wizard also sets the caps, purchase limits, schedule, terms, and presale whitelist. An optional vesting schedule delays delivery of purchased tokens and releases them over time. After creation, this Console surface edits only the whitelist. A Sale Admin can add, remove, or import addresses on its tab. Whitelist edits do not affect public-sale eligibility after the presale ends. The token sale endpoints expose adjustments such as the soft cap and purchase limits for integrations that need them.
What this screen does own in setup is funding and the go decision. The sale contract must hold the full hard cap in tokens before activation, and the banner states plainly whether it does. "Fund Sale" mints exactly the shortfall to the contract, so a partially funded sale is topped up rather than overfunded; the control needs the token's Supply Management role, because it is a mint on the token rather than a sale operation. "Activate Sale" then enables the sale under its configured schedule, and setup is over: after purchases begin, the contract holds investor payments and the one-way path in the figure governs.
Activation and opening are separate moments. Activate before the configured start time and the sale stays closed to buyers, with a banner naming the exact date it opens; a purchase attempted early reverts on-chain regardless of what any screen shows. Scheduling the activation ahead of the start is therefore safe, and it is the normal way to open a sale at a precise time without being at the keyboard.
The sale runs itself; you intervene by exception
An active sale needs no operator input. Where a presale is configured, it rolls into the public sale on its own when the configured presale end passes; a sale with no presale starts in public sale. Either way, the sale ends on its own at its end time or when the hard cap fills. The presale can use a discounted price and its own per-address cap. It also requires the buyer to be whitelisted. Public-sale buyers still need to meet the offering's other eligibility rules. Whitelist edits made after the presale has passed change nothing about who can purchase, and the Console says so on the "Whitelist" tab rather than letting you edit into a void.
Three interventions cut across that autopilot, and each carries a different cost. "Transition to Public Sale" ends the presale early; it is offered only while the sale is actually in its presale phase. "Pause Sale" stops new purchases on this sale only: nothing changes for the token itself, for its transferability, or for any other market that trades it, and "Resume Sale" reopens purchases where they left off. "End Sale" ends the offering permanently; there is no resume from it, so it is the one control here whose cost is irreversibility, and the confirmation says so before you sign.
Buying is gated before the click and explained after it
Before an investor reaches a purchase at all, the Console evaluates their eligibility and shows one of three verdicts. "Eligible" means the current pre-check found no blocker. State can change before execution. "Action required" means every blocking reason is one the investor can resolve, such as an unverified identity or a missing, revoked, or expired claim, and the Console routes them into that flow directly. "Not eligible" names a rule only an administrator can lift. A blocked investor can still open "Subscribe" and inspect the purchase sheet. Its submit control remains disabled until the eligibility blockers clear.
The purchase form validates before it submits. The form checks the first-purchase minimum, cumulative buyer maximum, and any presale cap. Returning buyers can top up below the first-purchase minimum. An amount beyond the sale's remaining headroom is reduced to that headroom, with a notice, instead of being sent to fail. Payment itself moves through an ERC-20 allowance: the sale contract pulls the payment currency from the buyer's wallet. The buy flow handles this itself, first raising the spend allowance if it is not already sufficient, then submitting the purchase, so the investor signs an approval only when one is actually needed.
When a purchase still reverts on-chain, the Console tells the buyer two things. The spend approval is in place, so approving again is wasted effort. And the sale contract refused for a specific, named reason. The named reasons are the contract's own. The buyer was not eligible, was not on the whitelist, or had not accepted the terms. The purchase would have crossed the hard cap or the buyer's own maximum allocation. The sale had not started, was not active, or its soft cap rule blocked the operation.
Finalization is a preview first and a transaction second
The rule is short. A sale with no configured soft cap always finalizes as a success. A sale with one finalizes as a success only if total tokens sold reached it. Once the sale has ended, "Finalize Sale" appears with a checklist beside it showing the soft cap status, the hard cap status, and the outcome those numbers predict. The checklist is a preview only; the on-chain finalize transaction is what actually decides and records the outcome. Until someone sends it, the sale sits in its ended state and every investor position stays undecided.
A successful finalization unlocks vesting. The claimable figure each investor sees is resolved entirely on the server, from the vesting schedule, any soft-cap hold, and any clamp already applied; the page never recomputes it. A zero after finalization is always explained: the position sits before its vesting cliff, was already claimed in full, has not started vesting yet, or has nothing unlocked yet at this point in the schedule. Before finalization, an ended sale shows a different message entirely, a hold naming the undecided outcome, with the progress bar locked until the finalize transaction resolves it. Success also frees the issuer's own "Withdraw Funds": unlike a failed sale, there is no waiting period, so the funds manager can pull the raise the moment finalization records success.
A failed sale pays investors back before it pays the issuer
Failure opens refunds, and refunds are per currency: each payment currency settles as its own independent transaction, because no single on-chain step refunds them all at once. Claiming all currencies from one verification step drives each one in sequence and reports partial progress as it goes. A currency that reverts keeps its failed status with the decoded reason inline, and does not roll back one that already settled; only the failed currency needs a retry. When everything is claimed, the section says so instead of showing an empty table.
The issuer's own "Withdraw Funds" is deliberately the last move. After a sale finalizes as failed, that withdrawal stays locked for thirty days from the moment of failure, so investors have a protected window to claim before the issuer can pull the remaining balance. The withdrawal itself asks for a recipient: it defaults to your own wallet, and a treasury address routes the raise elsewhere. The sale's own token is never offered as a withdrawable currency, because the contract was never holding it on the issuer's behalf; recovering unsold tokens is the separate "Withdraw Unsold Tokens" control.
Roles decide what the screen lets you sign
Two role systems meet on this screen, and confusing them is the most common dead end. Organisation-wide roles open doors: admin or token manager reaches the list and any sale's operating console. On-chain sale roles sign transactions: each entry under "Manage" requires a specific role held on the sold token's access manager, Sale Admin or Funds Manager for "Fund Sale", Funds Manager for "Withdraw Funds", and Sale Admin for "Activate Sale" and the remaining lifecycle controls. An organisation token manager who was never granted the per-sale role can open everything and sign nothing; each disabled entry names the role it needs.
The "Permissions" tab is where that gap closes: it assigns Sale Admin and Funds Manager on this sale without granting full token administration, and editing it needs the Admin or Sale Admin role on the token. The "Cap table" tab follows the same split. The tab appears when your account holds any privileged role on the sold token, but the request behind it answers only to a sale administrator or funds manager. An admin or token manager without one of those two sale roles sees the tab and has the request refused. Editing the "Whitelist" tab needs Sale Admin specifically. Fund Sale uses the shared sale-manager gate: either Sale Admin or Funds Manager on the offering's token; Activate Sale and other actions retain their role-specific requirements.
Steps
Open the offering list
In the Console, open "Asset lifecycle", then "Primary Offerings". The page lists sales across the organisation.
Screen equivalent: the organisation sales view lists each offering and provides the control to create a primary offering when your role permits it.
Create an offering
From the list, select "Create primary offering" and complete the wizard. In "Token & Pricing", the Currency picker lists eligible payment tokens; it does not list people or the sale token itself. If you dismiss the picker without choosing, the field reports "Select a payment currency." The wizard rejects selecting the sale token as its own payment currency before wallet confirmation. The Review step shows the same end time that appears on the created offering's Schedule, including windows that cross a daylight-saving change.
Open an offering
Select a sale to open its operating console. The banner reads the sale's current state, funding, and soft cap position; the tabs cover the overview, purchases, currencies, whitelist, vesting, marketing, and permissions. "Cap table" is the one tab that appears only when your account holds a privileged role on the sold token.
Run the state's operation from "Manage"
Open "Manage" and pick the control the sale's state offers. Setup offers funding and activation; an active sale offers transition, pause, resume, and end; an ended sale offers finalization; a final sale offers the withdrawals. The Console asks for wallet verification before each on-chain signature, and an entry your on-chain role does not cover stays disabled with the missing role named.
An equivalent flow exists for integrations: the token sale endpoints drive creation, activation, purchase, finalization, refunds, and withdrawals.
Troubleshooting
The list shows Access restricted
Your account lacks an organisation-wide admin or token manager role, which this cross-token view requires even for an account that administers one specific sale. Ask an organization administrator for access to the cross-token list. Alternatively, open the token's "Sales" tab: a Sale Admin or Funds Manager on that token can use its management view.
Create primary offering is disabled
The control needs two things at once: an organisation token manager role, and at least one token your account governs, because the wizard's token picker only offers governable tokens and would otherwise dead-end at submission. The tooltip you actually see names only the role, "Requires the system Token Factory role. You can still create an offering from a token you govern.", and it points at a real alternative: open that token's own "Sales" tab and create the offering from there instead of this cross-token list. Ask an administrator for the role, for governance on the token you intend to sell, or take the tooltip's own route and start from that token's page.
A Manage entry is greyed out with a role name
You opened the console through an organisation-wide role, but the entry itself needs an on-chain role on the sold token. Fund Sale needs either Sale Admin or Funds Manager; Activate Sale and other entries name their specific role. Have an account with Admin or Sale Admin on the token grant the role from the sale's "Permissions" tab, then retry; the grant is an on-chain transaction, so allow it to settle first.
Finalize Sale never appears although the end time passed
The sale was paused when its end time arrived, and a paused sale does not read as ended. Use "Resume Sale", after which the passed end time takes effect immediately and "Finalize Sale" appears, or use "End Sale" if the sale should close permanently regardless.
A purchase reverts after the spend approval already succeeded
Do not approve again for the same attempt: the toast already confirms the spend allowance is in place, and the failure is the sale contract's own decoded refusal. Match that reason against "Buying is gated before the click and explained after it" above, clear the underlying condition, an eligibility, whitelist, or terms gap, the sale's own numbers, or its timing, and resubmit the same amount.
A vesting position shows nothing claimable
The tile's own status label names the exact reason, so read that rather than guessing from the numbers. Before finalization it reads "Pending finalization"; see "Finalization is a preview first and a transaction second" above for what unlocks it. After a successful finalization it reads one of "Locked until cliff", "Fully claimed", "Not started", or "Nothing claimable yet", each resolved on the server from the vesting schedule.
A refund claim fails for one currency
The one documented cause is "NoContributionToRefund": this account made no purchase in that currency, so the row is stale, refresh the page instead of retrying. Other failures can include token restrictions or insufficient refundable balance. Read the reason and the prior transaction outcome before retrying; keep currencies that already settled unchanged.
Withdraw Funds is locked on a failed sale
The refund grace period is running: for thirty days from the moment the sale failed, the contract protects the refund pool and refuses the issuer's withdrawal. Wait out the window. The sale's own token also never appears among the withdrawable currencies; recover unsold tokens through "Withdraw Unsold Tokens" instead.
Frequently asked questions
Can investors pay in more than one currency?
Yes. A sale lists one or more payment currencies, each with its own price in that currency, and every purchase spends exactly one of them. One investor can buy several times in different currencies, which is why a failed sale refunds per currency rather than in one combined amount: each currency's contribution is tracked and returned in its own units.
Does pausing a sale change its schedule?
No. The start, presale end, and end times are fixed at creation, and the clock keeps running while purchases are stopped. A pause spends part of the sale window rather than extending it, so a long pause near the end can leave little or no time to buy after "Resume Sale". Only "End Sale" changes when the sale stops, and it does so permanently.
What happens to tokens that never sold?
They stay in the sale contract until a sale administrator recovers them with "Withdraw Unsold Tokens", which becomes available once the sale is finalized in either direction. Because activation requires funding the contract to the full hard cap, any sale that ends short of that cap holds unsold tokens worth reclaiming.
Who can see who the investors are?
The "Purchases" tab shows buyer wallet addresses to anyone operating the sale. Resolved identities, names, KYC status, and country, appear only in the "Cap table", whose request answers solely to a sale administrator or funds manager on that sale. Investors themselves see only their own purchases; the subscription view is scoped per buyer on the server.
Can the terms document change after investors accept it?
Not once the sale is active. The document's hash is recorded on-chain, and the contract accepts a new hash only while the sale is still in setup, before any investor has bought. A buyer must acknowledge terms when the sale requires them. An acknowledgment can be recorded during setup, before the hash becomes fixed, so have investors review and acknowledge the final activated terms. Retain the accepted hash and acknowledgment event as evidence.
Related concepts
Read Primary Offering for the funding and allocation model, including finalization and refunds.