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. 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
The commercial terms of the sale are 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, and the optional presale with its discount and per-address cap. An optional vesting schedule delays delivery of purchased tokens and releases them over time. No screen and no endpoint changes these terms after creation.
During setup, "Manage" offers two more settings. "Set Terms" records the hash of the terms documents you uploaded to the sale. While an uploaded terms document is not yet recorded, "Activate Sale" stays disabled and says so. "Set Subscription Step" changes the step that every buyer's running total must be a whole multiple of, and 0 switches the rule off. Both lock at activation. A Sale Admin can add, remove, or import presale addresses on the "Whitelist" tab at any time, but whitelist edits do not affect public-sale eligibility after the presale ends. To reduce what one investor may take after you build your book, set a per-investor allocation through the token sale endpoints. The Console has no control for it, and it stays available after activation.
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 stops taking purchases at its end time. A full hard cap does not end the sale: further purchases are refused, and the sale still waits for its end time or for "End Sale" before it can be finalized. 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.
Four 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. "Extend Sale" moves the end date later by a whole number of days, while the sale is active or paused; when vesting is configured, the end date cannot move past the vesting start. "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, the subscription step, the cumulative buyer maximum, and any presale cap. Returning buyers can top up below the first-purchase minimum, but every top-up must keep the running total on the subscription step. A per-investor allocation is checked on chain only. 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.
On a sale with a soft cap, a successful finalization releases the tokens the sale held, on the vesting schedule when one is set. A sale without a soft cap does not wait for it: tokens transfer at purchase, or release on the vesting schedule. 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, and after that the issuer can pull only the balance above the refunds that investors have not claimed yet. 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.
A successful sale can release a purchase it cannot deliver
A sale with a soft cap holds every buyer's tokens until a successful finalization, and a buyer can lose the right to receive them in that time: the wallet is frozen, or the identity verification lapsed. The "Cap table" tab shows each buyer's delivery state. When the sale can no longer deliver to a buyer, a funds manager sees "Refund undeliverable purchase" on that buyer's rows. The release returns the undelivered tokens to the unsold pool and records a refund of the undelivered share of the payment, in every currency the buyer paid in. The row then reads "Refund recorded", and "Pay out refund" pays one currency at a time to the buyer's wallet, or to the wallet that replaced it through identity recovery. A paid currency reads "Refund paid". The token sale endpoints expose the same two steps.
A buyer can also lose the wallet itself. When identity recovery replaces a lost wallet, the sale cannot deliver to the old wallet, and nobody can sign from it. The cap table then shows "Deliver to recovered wallet" on that buyer's rows once tokens can be withdrawn. The sale never offers a release for a recovered buyer, so the buyer keeps the tokens they paid for; before the first tokens vest, the rows show no action. It sends the tokens the buyer can withdraw now to the wallet that the identity registry names as the replacement. The vesting schedule still applies, so a vesting buyer gets each vested part the same way. Any wallet can send the delivery, because the sale takes the recipient from the identity registry and the caller cannot change it. The sale refuses the delivery for a buyer whose own wallet is not lost; that buyer withdraws as usual.
A sale with vesting and no soft cap records no payment per buyer, so it cannot calculate a refund and does not offer the release. When this sale cannot deliver to a buyer, for example because the wallet is frozen, the cap table marks the buyer's rows "Undeliverable, held in sale". The tokens stay in the sale, and the buyer keeps the right to them. A regulated issuer decides each case outside the platform, for example under a sanctions rule or a court order, and settles any repayment or seizure there. When the issuer lifts the freeze, or the buyer is verified again, the buyer withdraws as usual. Do not use a forced transfer to move held tokens out of the sale: the sale still counts them as owed to the buyer, so the transfer leaves the sale short for that buyer or for the unsold pool.
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 and 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, terms, the subscription step, and activation; an active sale offers transition, pause, resume, extend, 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. After it, the issuer can withdraw only the balance above the refunds that investors have not claimed yet, so a withdrawal can return zero while refunds stay unclaimed. 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 and presale 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". To give buyers that time back, use "Extend Sale" to move the end date later. "End Sale" stops the sale early, 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 the Console offers once the sale is finalized in either direction. Through the token sale endpoints, the withdrawal also works on a sale closed with "End Sale" before finalization, including a sale that was never activated. 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. In the Console, an investor's subscription view shows only their own purchases.
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.