On-chain primary sale
The partner journey from an onboarded customer to a settled on-chain primary purchase: which rail a market uses, what your backend holds, and where the platform refuses.
Your customer is onboarded and eligible. This page takes them from there to a settled purchase of a newly issued instrument. It is the on-chain counterpart to Off-chain sale, which covers the bank-transfer rail.
Read Integrating with Assetera first. The onboarding model you agreed, tied agent or distribution partner with a reliance agreement, decides who is responsible for the eligibility this page assumes.
What you build, and what you do not
| Who does it | |
|---|---|
| Show the instrument and the indicative price | you, from the catalog and the soft quote |
| Decide whether this customer may buy | Assetera, at every step, and finally at the intent call |
| Price the purchase | the offering's contract on chain, read by Assetera |
| Produce the settlement intent and its signatures | Assetera |
| Get the buyer's signature | you, in your frontend, with the buyer's wallet |
| Pay the gas | nobody: the call is relayed |
| Confirm the outcome | the chain, through the PrimarySettled event |
You never compute a price, a fee, or a quantity. Two implementations of the same rounding is how a one-wei disagreement ships, and here it would make a purchase revert at the delivery floor.
The journey
The endpoints, their request shapes and every refusal code are on Primary sale API.
Before you write any code
Read which rail the instrument uses. The market's primaryExecutionKind names it: bank transfer,
a third-party venue, or Assetera's own issuance. See
how you read the rail. The issuer chose it when the
instrument was onboarded, so it is catalog data rather than a request-time choice, and calling the wrong
rail returns a refusal rather than falling back.
Because the choice is not yours, plan for the catalog you are entitled to rather than for one rail. Cover both on-chain rails: they are deliberately the same shape, so that is one implementation, and an instrument whose rail you skipped is silently unbuyable in your app.
Register the buyer's wallet. The wallet must be registered and screening-approved before a firm quote will be issued for it, and it is the only address that can submit the settlement. A quote drawn for one wallet cannot be settled by another.
Keep the tokens in your backend. Which credential may reach the browser and which may not is the credential-boundary table on Partner onboarding.
Three things that surprise integrators
A firm quote can still be refused
Handing over the signed bundle is the last server-side check, so every eligibility rule is applied again at that moment: market lifecycle, the trading window, the buyer's eligibility, appropriateness for that asset class, and the trade-size limits. Design the journey so a refusal at the intent step is an ordinary outcome with a clear message, not an error screen.
Appropriateness is a gate, and it is completed in an Assetera flow
For a complex instrument the buyer must have completed the appropriateness assessment for that asset class. It is not scored and it cannot be failed, but it can be absent, and absent blocks the purchase. The assessment runs inside the Assetera onboarding flow embedded in your frontend, so plan for a hand-off in the middle of a purchase journey rather than discovering it at the intent call. See Compliance gating.
A primary purchase moves no chart
Primary sales do not produce a candle. Market data comes from secondary fills, and a primary purchase has no maker, no taker and no side, and inventing one would corrupt the market data. An instrument can sell steadily and show a flat chart, which is correct rather than a data gap. Do not build a "sales so far" figure out of chart data.
After settlement
The outcome is the PrimarySettled event, and every amount on it is a balance delta the router
measured rather than a number a venue reported. Do not read a return value; settlePrimary returns
nothing.
Assetera indexes that event, so you do not have to run an indexer to learn the purchase happened.
Which read endpoint reflects a primary purchase
Primary purchases are recorded on the Assetera side, but exactly which partner-facing read surface
they appear on, and how quickly, is not confirmed here yet. Until it is, treat the on-chain
PrimarySettled event as the authoritative confirmation for your own journey, and check the
OpenAPI contract for the read you need.
Next
Primary sale API
The endpoints, the quote lifecycle, and the refusal codes to branch on.
Primary issuance
What the contract does with the bundle you submit.
Partner onboarding
Credentials, identity, and what Assetera provisions for your tenant.
Off-chain sale
The bank-transfer rail, for markets that use it.
Off-chain sale (bank transfer)
Create a bank-transfer primary-sale purchase, show the returned payment instruction, and track reconciliation and delivery.
Environment and credentials
The full set of environment variables a tied-agent app needs, grouped by concern, plus how each credential is issued and why nothing is hardcoded.