Skip to content
SineraDocs

Create an Atom

Open a Commercial Atom from the Developer Portal, from terms to simulation to the on-chain outcome.

Atoms → New in the Developer Portal walks you through creating an Atom and escrowing its payment. The portal prepares and checks the transaction. Your wallet signs and sends it. Nothing is sent until you confirm in the last step.

Implementation candidate

Real tokens move

Creating an Atom moves tokens on the network named in the header and cannot be undone from the portal. The only public deployment is BSC Testnet. Check the network before you start.

Before you start

  • Sign in with the wallet that will pay. See the quickstart.
  • Your wallet must be on the same network as the portal header.
  • The payer needs enough of the settlement token for the gross value, and a little of the network's native coin for gas.
  • Have the counterparty's address ready.

Step 1: Terms

The bar at the top shows where you are. The Sign and Approve steps appear only when your terms need them. You can go back at any time before sending. Going back to the terms discards what was prepared from them.

GroupWhat you choose
PartiesYour role (buyer or seller), the counterparty's address, and the payer. The two roots must be different addresses.
PaymentThe settlement token and the gross value. The whole amount is escrowed when the Atom is created.
ObjectA required object reference that identifies what the Atom is for: free text (hashed for you) or a 32-byte value. Also whether this is a money Atom or an asset Atom with a quantity.
Consent and completionWhether the seller accepts later on-chain or signs now, and who may complete the Atom early.
Time policyThe acceptance, reacceptance, execution and challenge windows. Enter everyday units. The exact seconds appear under each field.
DisputesWhether either root may open a dispute on this Atom.
Intent deadlineThe time after which the prepared Atom can no longer be created.

The What your choices mean panel restates your choices in plain words and updates as you change them. If a field is wrong, Prepare and review marks it and says what to change.

Step 2: Review

The review states who pays what to whom, the protocol fee, each deadline as a time, and the rules of the Atom. Technical details shows exactly what your wallet will be asked to send: the network, the contract, the function, the sender and the predicted Atom id.

Steps 3 and 4: Sign and approve

These appear only when needed.

Sign. Some terms need a signature from a root before the Atom can be created. The step names who must sign.

  • If it is your connected account, choose Sign and approve the message in your wallet. The message is structured data your wallet displays. It is not a transaction and costs nothing.
  • If it is the other party, send them the message shown and paste the signature they return.

Approve. If the payer has not yet allowed the protocol to take the payment, the portal asks for a token approval of exactly the amount of this Atom. It never asks for an unlimited allowance. This is a separate transaction and costs gas.

Step 5: Simulate

The server runs the exact call against the latest block. You can continue only when the simulation succeeds. If it fails, the portal says why and what to change, for example an insufficient balance, a missing allowance, an expired intent deadline or a signature that does not match. There is no way to send a call whose simulation failed.

A successful simulation says the call would succeed on the block it ran against. The chain can change before your transaction is mined.

Steps 6 and 7: Send and read the outcome

Choose Send, read the confirmation, and approve the transaction in your wallet. The portal first checks that your wallet is on the right network and that the transaction is the one it prepared. If you reject the request in your wallet, nothing is sent and you can try again.

The portal then reads the result from the chain and compares it with what was prepared.

ResultMeaning
CreatedThe Atom exists with the predicted id. Open it from the link.
Mined, not finalThe transaction is in a block that is not final yet. The page keeps checking.
PendingThe network has not included the transaction yet.
RevertedThe transaction failed on-chain. Nothing was created. The reason is shown when the network provides it.
Id mismatchA transaction succeeded but did not create the prepared Atom. Treat this as an error and check the hash in Lookup.

When sending is turned off or unavailable

The operator of a portal decides, per network, whether the portal may ask your wallet to send. Where it is off, everything up to the simulation works as described, and the last step is Export instead of Send:

  • A token approval, if needed, is shown as the exact call to make. Make it with your own wallet or tools, then choose Simulate again.
  • After a successful simulation, copy or download the prepared transaction as JSON: chain id, sender, contract, call data, predicted id and the block it was simulated at.
  • Send it yourself, then read the result in Lookup with the transaction hash.

Sending is also unavailable when:

  • You signed in with a Sinera account. The portal cannot ask a browser wallet to sign in that kind of session. Sign in with the wallet instead.
  • The network is not deployed. Nothing can be created without a recorded deployment.
  • Your wallet is on the wrong network. Switch it to the network in the header.

If you leave after signing or approving but before sending, the portal warns you. An approval you already made stays on-chain. You can reduce it from your wallet.

Next steps