Primary Offering
A Primary Offering lets an issuer sell newly issued units once and resolve payment, allocation, and delivery or refunds as one on-chain outcome.
The sale binds inventory and funding to one outcome: delivery after success, or refunds when an optional minimum is missed.
A minimum raise is optional. Setting one moves delivery to finalization, and nothing finalizes until someone calls it.
Activation locks the offering's terms. Prices, limits, vesting, the presale and the terms are all fixed before the first purchase.
A failed offering refunds each investor in the currency they paid, and the issuer may sweep what is left thirty days later.
Why primary offerings matter
A Primary Offering lets an issuer sell newly issued units once and get one on-chain outcome instead of several separate ones. A single contract takes each subscriber's payment, decides that buyer's allocation against the terms the issuer configured, and resolves the whole sale into delivered tokens or a refund.
Asset Lifecycle names the platform's general argument for this: the cost of a tokenized instrument sits in the gaps between the systems around it, not in issuance itself. Each gap is a reconciliation the issuer has to run and defend. In a first sale, demand, payment, allocation, and delivery or refund usually live in separate systems: a subscription book, a payment rail, and a token-transfer step. Each handoff between them is a seam. A Primary Offering closes those gaps by making one contract responsible for all four steps, so there is no separate record of what investors were promised, what they paid, and what they received to reconcile after the fact.
This is not secondary trading. The tokens enter investor hands for the first time, directly from issuer-controlled inventory. A hard cap limits the total amount available and per-buyer limits prevent one subscription from exceeding its permitted allocation. An optional minimum raise, the soft cap, adds a success condition. If the offering does not reach it, finalization fails the offering and investors can reclaim their contributions.
The platform runs the distribution mechanics: eligibility checks, accepted payment currencies, allocation records, token release, proceeds withdrawal, and refunds. The issuer remains responsible for the legal offering terms, investor disclosures, pricing decisions, and any obligations outside the platform.
What you fix before the sale opens
Before a Primary Offering can accept purchases, an administrator activates it. Activation is the decision point: one call among the many setup calls that precede it, but the one that locks most of what you configured for the life of the sale. Before it, the offering is a draft you can rewrite. After it, the only route to a different term is to end this offering and run another.
| Term | Changeable after activation | What choosing wrong costs |
|---|---|---|
| Minimum raise (soft cap) | No | It decides whether buyers hold tokens on the day they pay or wait for finalization. Getting it wrong changes the experience of every investor, not just the outcome. |
| Vesting start, duration and cliff | No | Vesting cannot be added to a live sale, and it cannot be removed from one. |
| Presale window, price factor and per-address cap | No | The presale phase can be closed early, but its terms cannot be edited. |
| Terms document hash | No | The hash is set once during setup, from the uploaded terms documents. It cannot be replaced, so every subscription points to one version of the terms. |
| Payment currencies and their price ratios | No | You cannot add a currency for a buyer who asks after the sale opens. |
| Per-buyer minimum and maximum | No | The per-buyer maximum defaults to the hard cap, so leaving it unset means no per-buyer limit at all. |
| Hard cap, sale token and start time | No | These are set when the offering is created. |
| Sale end time | Extend only | You can lengthen the window, never shorten it, and never past the vesting start. |
| Presale whitelist membership | Yes | Edits stop having any effect once the presale window closes, whether or not anyone closed it on purpose. |
| Trading pause | Yes | Pausing and resuming is the only reversible state change in the sale. |
Activation also requires the sale to already hold the full hard cap of the sale token. An offering cannot open on inventory you intend to mint later.
One configured value decides whether a buyer walks away holding tokens or holding a claim.
Running the offering
A Primary Offering has two stages: setup, then active. Setup is where you configure the sale token, inventory cap, dates, prices, accepted payment currencies, buyer limits, and the optional presale, minimum raise, terms documents, and vesting. In the Console, create the sale first, upload its terms documents in the sale's document center, then use Set Terms. The active stage starts once the sale is activated, and purchases execute against that fixed configuration.
One offering can run two phases in sequence: an optional presale that admits only whitelisted buyers at a discounted price factor, then the public phase that admits any buyer who passes the token's eligibility rules. The phase does not turn over on a timer of its own. It turns over the next time anyone transacts with the sale after the presale window has passed, and an administrator can also open the public phase deliberately. Either way, once that window is behind you the whitelist no longer decides who may buy.
Each purchase takes payment in an accepted currency and records the buyer's token allocation. The sale rejects rather than partly fills, and it names the reason:
- outside the time window, or not on the presale whitelist while the presale is running: wait for the applicable phase or request approval for the buyer's address.
- terms not acknowledged when the offering requires them: acknowledge the current terms hash and resubmit.
- a payment currency the offering does not accept, or an amount too small to buy a whole token unit: switch to an accepted currency, or raise the amount.
- a result below the buyer's stated minimum output, reported as DALP-4300: raise the payment or lower the minimum output and resubmit.
- a buyer the token's compliance rules do not admit, reported as DALP-4045: get the missing identity claim issued before retrying.
- a per-buyer or presale cap already reached, reported as DALP-4227, or the hard cap, reported as DALP-4114: reduce the amount to what the remaining capacity allows.
Tell investors about one asymmetry: the per-buyer minimum binds only a buyer's first purchase, not the ones after it.
Finalization, and what waits on it
After the window ends, someone has to finalize the offering. Nothing does it automatically, no scheduler picks it up, and there is no deadline by which it must happen.
The call is open to anyone, which is the property that makes a forgotten offering recoverable rather than stuck. It needs the window closed first, either because the end time has passed or because an administrator ended the sale early. It then records one outcome: success when no minimum raise was configured or when the raise was met, failure otherwise.
Until that call lands on an offering with a minimum raise, everything waits. Buyers cannot withdraw their tokens and the issuer cannot withdraw proceeds. The Console flags the state as awaiting finalization once the window has passed. Watch that flag: it means finalization has not run yet, not that something failed.
After a successful finalization the funds manager can withdraw proceeds and buyers can take their tokens, subject to any vesting schedule. Unsold inventory comes back through its own withdrawal, which the sale administrator can call and which is available as soon as the offering has ended, without waiting for finalization.
When the raise falls short
A failed offering returns money, not tokens: with a minimum raise configured, no tokens ever left in the first place.
Each investor claims their own refund, in the exact currency they paid, and once per currency they used. An investor who funded in two currencies makes two claims. The accepted currency list is fixed at activation. Refunds use each buyer's recorded contributions.
For thirty days after the offering fails, the issuer cannot withdraw anything: the attempt is refused while the refund grace period is running (DALP-4270). After that grace period ends, the issuer may sweep what is left, and unclaimed refunds are part of what is left. Tell investors that a refund is a claim they have to make, not a payment that arrives.
How funding becomes an allocation
Each Primary Offering is an isolated contract bound to one sale token. It holds issuer inventory and buyer payments until the lifecycle opens the correct withdrawal path. Its configuration, phase, balances, and settlement outcome stay separate from every other sale, even when the same issuer runs several offerings.
At purchase time, the contract converts the payment amount through that currency's configured price ratio and the sale token's precision. It checks the active phase, time window, buyer identity and token compliance, terms acceptance when configured, buyer limits, remaining hard-cap capacity, and the buyer's minimum token output. Only then does it increase the buyer's purchase record and contribution record.
Allocation and delivery can occur at different times, and two independent settings separate them. A minimum raise defers delivery until successful finalization so a failed raise can refund cleanly. Vesting records the allocation at purchase and releases only the portion the schedule allows. Vesting accrues from the vesting start rather than from the end of the cliff, so at the moment the cliff ends, everything that accrued during it becomes claimable at once.
The outcome is terminal. Success and failure are both end states, and no path returns an offering to a live phase from either one.
The cap table: who bought in
Every offering has a sale manager's view of its investors, the cap table. It lists each buyer's activity in that sale, one row per payment currency the buyer used, with nothing brought in from before or after that sale. A secondary market trade never earns a row, because a transfer is not a purchase. The platform's general holder view, which tracks every wallet holding the token, answers that broader question instead.
If you know "cap table" as the record of who owns a company or an instrument across its whole history, DALP's feature under that name answers a narrower one. It is built only from this one sale's purchase records, so a buyer's stake in a different sale of the same token, or a transfer received afterward, never shows up here.
What a row represents
Each row aggregates one buyer's purchases in a single payment currency. It lists the buyer's wallet, its resolved name when the registry has one, KYC status, country, how many purchases the buyer made in that currency, the total committed, and the total allocation. A buyer who paid in two currencies gets two rows, one per currency, sorted by total allocation and tie-broken on the currency address so the two sit next to each other rather than merging.
That split changes what two response fields mean. investorCount counts distinct buyers, so it can run smaller than the number of rows. A row's purchaseCount counts only that buyer's purchases in that one currency, not their purchases across the whole sale.
A live view, not a snapshot
Each request rebuilds a cap table. The platform aggregates the sale's recorded purchases by buyer and currency, looks up each buyer's identity for KYC status, name, and country, and returns the combined rows.
Because of that, the same request can answer differently between two reads. A buyer's KYC status can move from pending to registered, and a purchase that settles after your first read appears on the second. If you need a point-in-time record, such as for an audit, export the cap table at that moment.
KYC badges
Each row's badge reads one of three values.
| Badge | What it means |
|---|---|
| Registered | An identity record was found with an active status. |
| Pending | The record exists but has not cleared. |
| Unknown | The registry holds no record at all for that wallet, which points at a wallet the registry has never seen rather than one still working through onboarding. |
Who can read a cap table
Four roles can open the tab. Two of them can open the table.
Every field in a cap table row is investor data, and the platform checks access at the API, before any of it leaves the server, not only at the Console's tab. The server resolves the caller's own wallets against the sale token's access manager and checks for exactly two roles there: sale admin or funds manager. Holding neither means nothing returned, only DALP-0006, an authorization error naming the roles it wanted.
Administrator and token manager open the Console tab but are not among the two roles the server accepts, so a caller who reaches the tab through one of those two alone is still denied at the API. A visible tab is never proof that the request behind it will succeed.
Integrating with the endpoint
For integrations, the cap table endpoint returns one row per buyer-currency pair rather than one row per buyer, alongside the sale's own totals; the endpoint reference lists the exact fields and types. The token address in that response can come back empty for a token the tenant has yet to index. Each row's two amount pairs, one for payment and one for tokens, carry a display decimal string and a raw exact integer string; sum the exact values in your own calculations, never the decimal strings, to avoid rounding.
The integration contract
A Primary Offering API follows the business lifecycle. You create and configure the sale before activation, submit purchases while it is active, then end and finalize it to resolve the offering's outcome. Token delivery can occur at purchase when no minimum raise or vesting condition defers it. The indexed sale record gives integrations the effective phase, totals, currencies, limits, and each investor's position.
Treat a submitted operation as a request, not as proof of completion. Asset Lifecycle documents the idempotency contract every servicing call on the platform shares: one key per business instruction, and the terminal Settlement VerdictA Settlement Verdict lets you report success only when an operation actually happened, not from acceptance alone, across four recorded end states.Read the concept, never acceptance, as the signal to trust. For a purchase specifically, that signal is not the whole proof: the operation must also appear in the buyer's purchased amount and per-currency contribution record before another system reports the subscription as settled.
Amounts use integer token units. Payment conversion depends on the configured currency ratio and on the decimal precision of both the payment currency and the sale token. A purchase also carries a minimum token amount. Because the token amount comes out of that currency ratio and precision conversion, the minimum protects the caller from accepting a lower allocation than expected. Preserve the payment currency beside each contribution because refunds and proceeds withdrawals use the recorded currency rather than one aggregate cash balance.
Configuration operations exist for the minimum raise, vesting, purchase limits and terms, and they are usable only while the offering is still in setup. The contract enforces that, not the request, so a call made against a live sale is accepted by the interface and refused on chain. Check the offering's phase before you send one.
Controls and evidence
When you review a Primary Offering, start with the controls enforced when each subscription executes. The buyer must have a registered identity and must satisfy the sale token's configured compliance rules. A presale phase adds a whitelist gate that limits who may buy, and that gate stops applying when the presale window closes. Separately, minimum, maximum, presale, and total caps limit how much any buyer can be allocated.
The issuer binds the terms documents to the offering. The issuer uploads them as terms documents on the sale, and the platform derives the terms hash from the uploaded files; a caller cannot send a hash of its own. The issuer then records that hash on the sale contract once during setup. The contract refuses a second hash and refuses acknowledgement and purchase until a hash exists. Each buyer must acknowledge the hash on chain before purchase, and a purchase without that acknowledgement reverts. Acknowledgement is stored against the buyer's address, and the hash it points to never changes. Retain the acknowledgement event's hash when you check consent. For the call sequence, read Sale terms and acknowledgement.
The sale contract records its configuration, phase transitions, purchases, buyer allocations, contributions by payment currency, outcome, token withdrawals, proceeds withdrawals, and refunds. That record proves what the on-chain mechanism accepted and paid. It does not prove that disclosures were adequate or that an investor met obligations outside the configured identity and token rules.
Frequently asked questions
What does pausing a sale actually stop?
Pausing blocks two things: new purchases, and token withdrawals for buyers who already qualify to receive them. It does not touch refund claims, proceeds withdrawal, or extending the sale end time, all of which keep working while paused. Unpausing restores whichever phase the sale was in before the pause, and finalizing an offering lifts a pause automatically, so nobody stays locked out once the sale ends.
Is there a limit to how many payment currencies a sale can accept?
Yes, ten at once. Adding an eleventh is rejected on chain, not just blocked by the interface. Removing a currency during setup frees the slot, so you can retire one and add a replacement without ever carrying more than ten accepted at the same time.
What happens to excess or unsuccessful demand?
A purchase that would exceed the remaining hard cap, a per-buyer limit, or the presale cap is refused, not partly filled. The caps themselves never produce a smaller-than-requested allocation, though the ratio and precision conversion still can, which is what the buyer's minimum output guards against. Unsuccessful demand is different: if the offering later misses its configured minimum raise, every already-accepted contribution becomes refundable, one claim per currency the buyer used, and the issuer cannot touch it until the refund grace period ends.
Nobody finalized our offering and the window closed weeks ago. Is it lost?
No. Finalization has no deadline, and anyone, not only the issuer or an administrator, can trigger it. An offering sitting unfinalized for weeks is waiting, not stuck, and the outcome it eventually records depends only on whether the raise cleared its minimum by the time the window closed, not on when the call finally lands. Proceeds and refunds become available the moment finalization runs; token delivery under vesting keeps accruing from the vesting start throughout the delay, so a late finalization does not shrink the buyer's claimable amount.
Can the vesting start date fall before the sale ends?
No. The vesting start must be at or after the sale end time. Set a vesting start earlier than that and the call reverts rather than silently clamping to a valid date.
Asset Lifecycle
Asset Lifecycle is the whole working life of a regulated tokenized instrument, from issuance through servicing to redemption, governed on one platform.
Corporate Action
A Corporate Action pays a coupon, a dividend, or a matured redemption straight to token holders, turning an issuer's announced terms into an on-chain payout.