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 cannot withdraw a refund that is still unclaimed.
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. |
| Subscription step | No | Every buyer's running total must land on a whole multiple of the step. A step that does not divide the per-buyer minimum is refused. |
| 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. |
| Per-investor allocation | Yes | A lower allocation stops further purchases by that investor. It never takes back tokens the investor already bought. |
| 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, subscription step, 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. Activation ends setup, and from then on 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, presale, or issuer-set per-investor allocation cap already reached, reported as DALP-4227, or the hard cap, reported as DALP-4114: reduce the amount to what the remaining capacity allows.
- a running total that would not be a whole multiple of the subscription step, which the platform API refuses before it sends the purchase, reported as DALP-0686: change the amount so the buyer's total lands on the step.
Tell investors about one asymmetry: the per-buyer minimum binds only a buyer's first purchase, not the ones after it. The subscription step has no such exception. It applies to the running total after every purchase, so a top-up must also keep the total on the step.
Subscription step and per-investor allocations
Two settings shape how much each investor can hold, and they answer different needs.
A subscription step makes every holding a whole multiple of a fixed lot, for example 1,000 units for an instrument that is only issued in that denomination. Without it, the per-buyer limits allow any amount between the minimum and the maximum. The step is a setup term: a sale administrator sets it during setup, in the creation wizard or with the sale's own setting, and it is fixed at activation. A step of zero switches the rule off.
A per-investor allocation reduces what one investor may take after the issuer has built its book, for example when demand from one institution exceeds what the issuer wants to place with it. The allocation applies on top of the per-buyer maximum and the hard cap, and the smallest limit wins. Unlike the other limits, a sale administrator can set or clear an allocation at any time, including after activation, through the token sale endpoints. An allocation below the per-buyer minimum is refused, because the investor could then never make a first purchase. An allocation of zero removes the investor's cap.
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 sale contract accepts the call from anyone, which is the property that makes a forgotten offering recoverable rather than stuck. Through the platform, a sale administrator or funds manager sends it, and in the Console a sale administrator does. 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.
An offering that was never activated cannot finalize: the call is refused with DALP-4279. Its inventory is not lost. A sale administrator ends the sale from setup, then withdraws the unsold tokens, which in that case are all of them.
Until that call lands, the issuer cannot withdraw proceeds, whether or not a minimum raise is configured. On an offering with a minimum raise, buyers cannot withdraw their tokens either. 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 calls. The contract allows it after finalization, or earlier when an administrator ended the sale with an explicit end. When the end time passes with no explicit end, the offering still needs finalization first, and the Console offers the withdrawal only after finalization. After a success, tokens that buyers bought and have not yet withdrawn stay in the sale. After a failure, every token counts as unsold.
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 withdraw only the balance above the refunds that investors have not yet claimed. A refund claim has no deadline, so an unclaimed refund stays in the offering until its investor claims it. One exception: a contribution taken before the offering's contract was upgraded to this reserve is protected only by the grace period. 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 amount in a row, such as the payment committed or the tokens allocated, comes as a pair: 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.
The creation request carries the sale's commercial terms: payment currencies and prices, the hard cap, purchase limits, the minimum raise, vesting, and the presale discount and per-address cap. No later operation changes them. After creation, the platform exposes two setup operations, the terms hash and the subscription step, and the contract accepts both only while the offering is still in setup. Check the offering's phase before you send one. The per-investor allocation, the presale whitelist, and an end-time extension stay available after activation.
Sale events
Each step of a sale reaches your systems as a webhook event, sent once the block that holds it is final. The lifecycle events are sale activated, sale extended, sale closed, and sale finalized, which reports the success or failure outcome. Money and token movements arrive as subscription, delivery, refund, and proceeds withdrawn events. The primary market event catalogue explains when each event is sent and what your receiver does with it.
Do not wait for a closed event to learn that a sale is over. A sale that reaches its end time without an explicit end sends none, and its outcome arrives with the finalized event. Pausing, resuming, and an early move to the public phase send no lifecycle event.
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 until a hash exists. The platform also refuses a purchase while uploaded terms documents have no recorded hash. 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 withdraw it while it stays unclaimed.
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.