Primary Offering

What you fix before the sale opens#

Before a Primary Offering can accept purchases, a sale administrator activates it. When the organisation's approval policy has the offerings family on, activation waits for an organisation owner other than the requester, and so do creating, ending and resuming the sale. Activation 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.

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 exception is a book-built offering whose settlement mints the shares: it holds none of the offering, needs no funding, and activates once the sale holds the supply management role on the token. Such a sale is put in application mode before anyone funds it: once it holds any of the offering, the platform refuses the switch, because its settlement would issue those shares a second time.

That role lets its holder mint and burn the token. The sale's code uses it only to mint allocations at settlement, a system manager who repoints the token-sale factory can change that code, and the role stays with the sale until a token administrator revokes it.

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 on the sale's “Marketing” tab, 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 a sale 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 a purchase instead of partly filling it, 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.

The per-buyer minimum binds only a buyer's first purchase. 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#

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 belongs to the investor's identity instead of one wallet. Every wallet registered to that identity shares the allocation and the amount already bought, and a wallet that replaced a lost wallet through identity recovery keeps the lost wallet's allocation. A sale counts purchases per identity only from the point it adopted identity-keyed allocations, so earlier purchases do not count toward the allocation. The allocation applies on top of the per-buyer maximum and the hard cap, and the smallest limit wins.

Unlike the other limits, an allocation can change after activation. A sale administrator sets or clears it at any time, with no second approval, in the Console “Allocation caps” section of the offering or 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.

Finalisation, and what waits on it#

After the window ends, someone has to finalise the offering. Nothing finalises an offering automatically and no deadline applies.

The sale contract accepts the call from anyone. Through the platform, a sale administrator or funds manager sends it, and the Console offers Finalize offering to either role. When the Offerings row under Approvals in the organisation settings is on, finalisation is a maker-checker step: the platform sends it only after an organisation owner other than the requester approves. An organisation whose only owner is the requester cannot finalise through the platform while the row is on, because the request is refused when it is made. The approval governs the platform's call only, so it cannot stop a wallet outside the platform from finalising. Finalisation needs the window closed first, either because the end time has passed or because a sale 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 finalise: 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. Both steps go through the Platform API, because the Console offers End only while the sale is running or paused, and the withdrawal only once the sale is finalised.

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 finalisation once the window has passed and finalisation has not run.

After a successful finalisation the funds manager can withdraw proceeds to an address the funds manager names in the call, 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 finalisation, or earlier when a sale administrator ended the sale with an explicit end. When the end time passes with no explicit end, the offering still needs finalisation first, and the Console offers the withdrawal only after finalisation. After a success, tokens that buyers bought and have not withdrawn stay in the sale. After a failure, every token counts as unsold.

Through the Platform API, withdrawing proceeds or unsold inventory and starting an undeliverable-purchase refund require a Console-issued session. A Portal-issued session, an anonymous session or a session with no recorded issuing app answers 403 Forbidden with WALLET_ROLE_ADMINISTRATION_NEEDS_CONSOLE_SIGN_IN (DALP-200384), before any withdrawal or refund starts. Sign in to the Console and retry. API keys keep the route's existing access policy. Investor purchases, token claims and refunds of their own purchases do not require a Console session.

An investor with several ended offerings to settle can settle them in one call, POST /api/v2/addons/token-sales/investment-settlements, naming up to 20 sales. It asks for the wallet verification once. For each sale it then withdraws the tokens a successful sale owes now, or claims a refund for each currency a failed sale still holds. Each claim or refund is its own transaction, and one that fails does not stop the others. The answer lists one result per claim or refund. A sale that owes the acting wallet nothing comes back skipped, so an investor with several custody accounts settles each account in its own call. A browser wallet cannot settle several sales in one call. It signs each claim or refund through the sale's own routes.

When the raise falls short#

When an offering fails, the sale refunds what investors paid. With a minimum raise configured, no tokens have left the sale.

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 beyond the refunds that investors have not 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 must make.

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 finalisation 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 instead of 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: no path returns a succeeded or failed offering to a live phase.

Book-built offerings: greenshoe and lock-ups#

A sale in application mode is a book-built offering. Investors do not buy tokens at once. Each investor applies with a payment that the sale holds in escrow, the sale closes, and an allocation run divides the offering between the applicants pro rata when demand exceeds it. The settlement then mints each allocation to its investor, pays the issuer's recipient for the shares allocated and refunds the rest. Two optional terms, set while the sale is in setup, shape that outcome: a greenshoe and a lock-up per investor category.

The allocation run, its approval and the reclaim#

After the sale ends, the sale admin requests one allocation run and names the recipient of the payment. The run allocates as sale admin and settles as funds manager, so the signing wallet needs both roles. The preview lists every applicant with demand, allocation and refund, plus the unissued leftover from rounding down and the total kept per currency, and fixes them with the book hash. A request that names an older hash is refused. Once settling starts the recipient is bound, and a run that names another recipient is refused.

When the offerings family of the organisation's approval policy is on, the run waits for a second approver, an organisation owner other than the requester. The approval binds the platform's request only: a wallet that holds the two roles the run signs with can allocate and settle on chain directly, without it. The request is open for seven days, and on approval the run recomputes from the chain and stops if the book moved since the request. A request in an organisation whose only owner is the requester is refused when it is made. When the family is off, the run starts on the request.

If the allocated book does not reach the soft cap, finalisation fails the offering. Nothing is allocated and every applicant is refunded in full. Investors never claim after a run, because the tokens and the refund arrive together in the settlement.

If the sale admin does not start the run within 30 days after the sale ended, each application reads Reclaim due. No run can start after that, and every applicant takes the whole escrow back in every currency they paid in, with one wallet verification. A reclaim ends a running or paused sale, so it cannot be extended afterwards.

The greenshoe#

A greenshoe lets the offering grow above its hard cap at the offer price when demand allows. The sale admin sets its maximum as basis points of the hard cap and chooses who decides how much of it is used. The sale stores that maximum and adds at most the hard cap times it, rounded down to whole tokens. On a token with a supply cap, it adds no more than the room the cap leaves above the current supply and the hard cap. The most a sale can store is 65,535 basis points. Zero removes it.

A discretionary exercise is a whole number of tokens, at most the capacity, the demand above the hard cap and, on a capped token, the room left under the supply cap. Without an exercise the offering stays at the hard cap. The exercised amount is part of the book that the approver of the allocation run reviews, so an exercise changes the book hash and a run requested before it must be requested again.

The over-allotted shares are new shares. The settlement mints them like the rest of the allocation, so the sale needs the supply management role on the token, and the issuer is paid for them in the same run. The allocation divides the hard cap plus the exercised greenshoe, with the same pro rata rule and rounding as a plain oversubscribed offering, so tokens sold can exceed the hard cap by the exercised amount. A first-come sale takes no greenshoe: it has no point at which demand above the offering is known, so it sets a larger hard cap instead. A sale reads its greenshoe and its application book through the application-mode endpoint, where offeringExact is the hard cap plus the greenshoe and greenshoeExact is the part the greenshoe adds.

Both terms need a sale whose contract carries them: the greenshoe needs the fifth sale implementation, and the lock-up schedule, even a single step, needs the sixth. A sale runs the sale implementation its system's token-sale factory points at, so while that factory points at an earlier implementation, its sales have no greenshoe and no lock-up to set: the write is refused with DALP-200382 and no transaction is sent. A holder of the system manager role, or the add-on registry, points the factory at an implementation, and the factory checks only that the new code reports two interfaces through ERC-165: the token sale interface and the interface of a contract with its own on-chain identity. Because each sale reads its implementation from the factory on every call, that change applies to every sale of the system at once, live sales included, and neither a sale administrator nor a second system manager approves it.

Lock-ups per investor category#

A lock-up keeps an allocation from moving, in steps, after delivery. The sale admin sets up to eight categories, each a claim topic on the investor's identity such as qualifiedInstitutionalInvestor with an unlock schedule, and a default schedule for investors in no category. For each applicant the settlement checks the categories in the order given. The first category whose claim topic the investor's wallet is verified for sets the schedule, so list the strictest schedule first.

A schedule has up to four unlock steps. Each step is a share of the allocation in basis points and a wait from the first delivery of the settlement in seconds. The shares of one schedule add up to 10,000, each step unlocks after the one before it, and a wait is at most 1,826 days. A step whose wait is zero and whose share is the whole allocation locks nothing, and so does a schedule with no steps. One step that releases the whole allocation is a plain lock-up duration.

The lock is written in the token's lock-up compliance rule, in the same transaction that mints the allocation, so no ordinary transfer can move the shares unlocked. A forced transfer by the token's custodian role skips compliance rules, the lock-up rule included. A one-step schedule writes the rule's single holder lock. A multi-step schedule writes one tranche per step that is still locked when the allocation is delivered. Every schedule runs from the first delivery of the settlement, so all investors of one category unlock each step at the same moment. Until a step unlocks, the rule refuses any transfer that would leave the sending wallet with less than the share still locked, so the unlocked share can move. The shares still pay dividends and carry votes.

An investor who already holds an active single lock keeps it: the amounts add up and the later unlock time applies. Vesting tranches are added beside a single lock without moving its unlock time. A step whose unlock would already have passed writes no tranche.

A sale with lock-ups needs two things on its token before it activates: an active lock-up rule, and the governance role for the sale's address, which the rule requires to write a holder lock. The governance role lets its holder change the token's compliance, identity registry and features. The sale's code uses it only to write holder locks on its own token's lock-up rule, and a system manager who repoints the token-sale factory can change that code. A schedule with more than one step also needs a rule that stores unlock steps. Without the rule the activation is refused with DALP-4526, without the role with DALP-4527, and a multi-step schedule on a rule that stores one lock with DALP-4529. A schedule whose shares do not add up to 10,000, or whose steps do not unlock in order, is refused with DALP-4528. A settlement batch also stops when the rule is removed or turned off after activation. It stops with DALP-4530 when the delivery would pass the eight unlock steps one holder identity stores on a token. No allocation is delivered unlocked.

Read each applicant's result in the lockup field of the application: the locked amount across every step, the unlock time of the last step, the claim topic of the category, which is null for the default schedule, and tranches, one entry per step with its amount and unlock time.

The cap table: who bought in#

Every offering has a view of its investors for its sale administrators and funds managers, 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 instead of merging. When a sale holds tokens for a buyer, the row also says whether the token refuses to deliver them to the buyer's wallet (undeliverable) and whether they can go to the wallet that replaced a lost one through identity recovery (recoveredWalletDeliverable). The Console shows both as a delivery state and offers the matching action to the funds manager, such as refunding an undeliverable purchase.

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.

The cap table is rebuilt on every request#

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.

Who can read a cap 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. A caller with neither role gets no data and receives DALP-0006, an authorisation error with HTTP status 403 that says the acting wallet lacks a role the action requires.

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 instead of 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 finalise 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.

A submitted operation is a request. Asset Lifecycle documents the idempotency contract every servicing call on the platform shares: one key per business instruction, and the terminal Settlement Verdict as the signal to trust. For a purchase, also check that the amount appears 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 instead of 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, a sale administrator can still set the terms hash, the subscription step and, for a book-built offering, the book-building mode, the greenshoe and the lock-ups. The contract accepts each of these 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 finalised, which reports the success or failure outcome. Money and token movements arrive as subscription, delivery, refund, and proceeds withdrawn events. A book-built offering sends none of its application, greenshoe, lock-up, allocation or reclaim steps as a webhook, so read them through the applications and allocation-run reads. 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 finalised 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. Through the platform, the terms hash is derived from the uploaded files and a caller cannot send one of its own. The contract itself accepts any hash from a sale administrator during setup, so check that the recorded hash matches the published documents. 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.

Offerings belong to the Primary market licensed module, which the deployment switches on with features.tokenSale in the Helm values. An organisation can opt out of it in Organisation settings. Its offerings then stay readable in the Console and the Investor portal, both apps hide their write controls under a read-only banner, and every write route refuses with 403 and platform.module.DISABLED (DALP-20531), investors' own purchases, token withdrawals and refund claims included. Switch the module back on to resume. The switch closes the platform's routes only. The sale contracts still accept calls sent to them directly, so pause or end a sale on chain to stop it.

Frequently asked questions#