Tokenize an asset and run an STO

Every step below is the same three moves: prepare an unsigned transaction, sign it with your whitelisted wallet, send it. The examples target Sepolia (aa36a7) on sandbox, so nothing here moves real value.

Before you start

Get an API key

Request one. Every call below needs x-api-key.

Get your signer registered

Brickken registers the wallet you pass as signerAddress in the factory. Include that address in your API key request. If you did not, or you want to use a different wallet, send it to tech@brickken.com — there is nothing for you to do on-chain, and no separate whitelist call to make.

Fund that wallet with native gas

You broadcast the transactions, so the signer pays the gas — Sepolia ETH here.

The wallet that performs the first newTokenization becomes the tokenizer for that token. Only the tokenizer can mint it, whitelist its investors, or distribute its dividends. Transfers and burns can come from any wallet. Your API key is also scoped to the symbols it tokenized — anything else returns Unauthorized token symbol.

The sign-and-send loop

You will repeat this after every prepare, so it is worth writing once. Prepare returns { txId, transactions }:

curl --request POST 'https://api.sandbox.brickken.com/send-transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \
  --data '{
    "txId": "0xPreparedTransactionId",
    "signedTransactions": ["0xSignedRawTransaction"]
  }'

Signing, with ethers:

import { Wallet } from "ethers";

const wallet = new Wallet(process.env.PRIVATE_KEY!);
const signedTransactions = await Promise.all(
  prepared.transactions.map((tx) => wallet.signTransaction(tx))
);

Then poll until it confirms:

curl 'https://api.sandbox.brickken.com/get-transaction-status?txId=0xPreparedTransactionId' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY'

pending means broadcast but not yet mined. Do not resubmit — you would pay gas twice.

Treat every successful transaction as a dependency boundary. Before preparing newSto, mintToken, or whitelist, poll the preceding newTokenization until it succeeds. A send response only means the transaction was broadcast; a reverted receipt does not create the token record used by later methods.

Already run your own broadcasting? Add "executionMode": "client-broadcast" to any prepare below, submit the signed transaction to the chain yourself, then confirm with { txId, txHash } instead of { txId, signedTransactions }. Brickken reconciles your hash so the transaction still appears in get-transaction-status and in the dApp. See Send Transactions.

1. Create the tokenized asset

curl --request POST 'https://api.sandbox.brickken.com/prepare-transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \
  --data '{
    "method": "newTokenization",
    "signerAddress": "0xYourWhitelistedWallet",
    "chainId": "aa36a7",
    "tokenizerEmail": "issuer@example.com",
    "name": "Example Asset",
    "tokenSymbol": "EXMPL",
    "tokenType": "EQUITY",
    "supplyCap": "1000000",
    "url": "https://example.com/token-docs"
  }'

The field is name, not tokenName. tokenType accepts EQUITY, DEBT, BILL_FACTORING, ICO, STABLECOIN, REVENUE_SHARE, RWA_TOKEN, or PROFIT_SHARING, and defaults to EQUITY. supplyCap defaults to 0, which means uncapped — set it deliberately. Sign and send, then confirm the token exists. The endpoint lists all symbols available to your API key; use the exact confirmed symbol in every later request.

curl 'https://api.sandbox.brickken.com/get-token-info' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY'

Every field, with the request and response schema, is on the newTokenization reference.

2. Whitelist your investors

Testing in Sandbox? Pass needKyc: false and skip identity verification entirely. The KYC flow is a Sumsub verification with document upload, not something you need to prove your integration works, and every test investor you create without it is one less manual step in your loop.Rehearse the real KYC flow once before you go live, since needKyc: false is rejected in production with needKyc=false is only available in the sandbox environment.

A security token only moves between whitelisted wallets. Whitelist before you mint or accept investment.

curl --request POST 'https://api.sandbox.brickken.com/prepare-transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \
  --data '{
    "method": "whitelist",
    "signerAddress": "0xYourWhitelistedWallet",
    "chainId": "aa36a7",
    "tokenSymbol": "EXMPL",
    "userToWhitelist": [
      {
        "investorAddress": "0x1111111111111111111111111111111111111111",
        "investorEmail": "investor@example.com",
        "whitelistStatus": true
      }
    ]
  }'

whitelistStatus: false removes an investor. Verify with GET /get-whitelist-status.

3. Mint tokens

curl --request POST 'https://api.sandbox.brickken.com/prepare-transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \
  --data '{
    "method": "mintToken",
    "signerAddress": "0xYourWhitelistedWallet",
    "chainId": "aa36a7",
    "tokenSymbol": "EXMPL",
    "userToMint": [
      {
        "investorEmail": "investor@example.com",
        "investorAddress": "0x1111111111111111111111111111111111111111",
        "amount": "100",
        "needWhitelist": true
      }
    ]
  }'

needWhitelist: true whitelists the recipient as part of the same mint, which collapses step 2 into step 3 when you are onboarding a new investor.

investorEmail must identify an investor distinct from the asset’s tokenizerEmail. Do not use the issuer/tokenizer email as the mint recipient: it can conflict with the issuer account in the investor records. The recipient may use the same wallet address as the tokenizer for sandbox testing; only the email identities must differ. needWhitelist controls the whitelist sub-step and does not change this identity rule.

4. Launch the offering

curl --request POST 'https://api.sandbox.brickken.com/prepare-transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \
  --data '{
    "method": "newSto",
    "signerAddress": "0xYourWhitelistedWallet",
    "chainId": "aa36a7",
    "tokenizerEmail": "issuer@example.com",
    "tokenSymbol": "EXMPL",
    "tokenAmount": "1000",
    "offeringName": "Series A",
    "startDate": "2026-09-01T00:00:00.000Z",
    "endDate": "2026-12-31T23:59:59.000Z",
    "acceptedCoin": "USDT",
    "minRaiseUSD": "10000",
    "maxRaiseUSD": "100000",
    "minInvestment": "100",
    "maxInvestment": "10000"
  }'

Every one of those fields is required. acceptedCoin is a payment token symbol — USDT, USDC, or BKN — and minRaiseUSD is the offering’s soft cap. There is no tokenPrice field: the price is derived as maxRaiseUSD / tokenAmount. tokenAmount, not totalTokensOffered, is the supply on offer, and the payment token field is acceptedCoin, not paymentTokenSymbol — those three wrong names are the most common cause of a rejected newSto.

Send both dates as explicit UTC, with the Z suffix shown above, or as a unix timestamp. A timestamp with no offset is read as UTC by the server, so a local-time value schedules the offering at a different moment than you intended, and every investment in that gap reverts with IssuanceNotStarted.

startDate is checked against the block timestamp when the STO transaction is mined, not when you prepare it. Set it at least 10 minutes after the time you expect to call send-transactions, then sign and broadcast promptly. A date that has elapsed while signing, sending, or waiting for inclusion causes the transaction to revert even when prepare and send succeeded.

Once it is live, list your offerings and keep the uuid:

curl 'https://api.sandbox.brickken.com/get-stos?chainId=aa36a7&tokenSymbol=EXMPL' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY'

5. Take an investment

Note there is no signerAddress in the required set — the investor signs this one, not the tokenizer.

curl --request POST 'https://api.sandbox.brickken.com/prepare-transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \
  --data '{
    "method": "newInvest",
    "chainId": "aa36a7",
    "tokenSymbol": "EXMPL",
    "investorEmail": "investor@example.com",
    "investorAddress": "0x1111111111111111111111111111111111111111",
    "investmentAmount": "1000",
    "paymentTokenSymbol": "USDT"
  }'

newInvest prepares the investment transaction only. Before calling it, the investor must already have a whitelisted wallet, the payment token in that wallet, and an allowance towards this offering’s escrowAddress — prepared separately with approve and confirmed on-chain. Allowances are per spender, so an allowance granted for another offering does not count.

The whitelist and the allowance are enforced by the contract, not by an API precondition check, so a missing one comes back as a revert rather than a readable message. See Troubleshooting.

Track progress with GET /get-investments-by-sto-id and GET /get-sto-balance.

6. Close the offering

An offering can only be closed once its endDate has passed — there is no early close and no override. Closing finalizes the issuance, which is what unlocks claiming.

curl --request POST 'https://api.sandbox.brickken.com/prepare-transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \
  --data '{
    "method": "closeOffer",
    "signerAddress": "0xYourWhitelistedWallet",
    "chainId": "aa36a7",
    "tokenSymbol": "EXMPL",
    "tokenizerEmail": "issuer@example.com"
  }'

If the raise reached minRaiseUSD, the offering is successful and investors receive tokens. If it did not, the issuance enters rollback and investors are refunded instead.

7. Let investors claim their tokens

Only after the offering has been finalized. The investor signs this one.

curl --request POST 'https://api.sandbox.brickken.com/prepare-transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \
  --data '{
    "method": "claimTokens",
    "chainId": "aa36a7",
    "tokenSymbol": "EXMPL",
    "investorEmail": "investor@example.com",
    "investorAddress": "0x1111111111111111111111111111111111111111"
  }'

The same call refunds the payment token instead of releasing tokens when the offering rolled back.

8. Distribute dividends

curl --request POST 'https://api.sandbox.brickken.com/prepare-transactions' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \
  --data '{
    "method": "dividendDistribution",
    "signerAddress": "0xYourWhitelistedWallet",
    "chainId": "aa36a7",
    "tokenSymbol": "EXMPL",
    "amount": "1000"
  }'

Only the tokenizer can do this. Read the result with GET /get-dividend-distribution.

When something fails

Response	What it means
`401` / `400 API key is missing`	No `x-api-key`, or this endpoint needs one and did not get it
`Unauthorized token symbol`	Your key did not tokenize that symbol
`Out of credits for <method>`	Your plan’s balance for that specific method is exhausted
`429` + `Retry-After: 60`	Rate limited on `prepare-transactions`
Prepare rejects your `signerAddress`	It is not a valid EVM address, or not the wallet associated with that asset. An API key does not require a separately whitelisted signer address
`No company found with this token symbol`	The symbol is not a successfully confirmed asset on that chain; inspect `GET /get-token-info` and use the exact symbol it lists
Mint returns a uniqueness conflict	The recipient email is already the asset’s tokenizer email; use a distinct `investorEmail`
`newSto` reverts after send	`startDate` became past or too close by the mined block; retry with at least a 10-minute send-time buffer
Send reverts on-chain	Usually an unwhitelisted recipient, an unapproved allowance, or no gas
`Tokenizer already has an ongoing STO`	A token can have only one ongoing offering; wait for it to end
`newInvest` reverts with `IssuanceNotStarted`	The offering has not opened. Send `startDate` as explicit UTC with a `Z` suffix
`newInvest` reverts with panic `0x11`	Zero allowance to this offering’s escrow, or not enough payment token
`closeOffer` reverts with `IssuanceNotEnded`	The `endDate` has not passed. There is no early close
`claimTokens` reverts with `IssuanceNotInRollback`	The offering has not been finalized; run `closeOffer` first
`Insufficient allowance to distribute dividends`	Approve the payment token, with the security-token address as spender

Each write method has its own credit balance, so exhausting mintCredits does not block newSto. See Authentication for plans, scoping, and the full error reference. For decoding raw revert data and the full symptom-to-cause list, see Troubleshooting.

Doing this without writing HTTP

MCP server

The same lifecycle as agent tools — create_tokenization, create_sto, mint_tokens — driven by an AI agent with just your API key.

Postman collection

Every request above, ready to run.

Overview

Guides

Prepare Transactions

Send Transactions

Read Endpoints

Token Documents

KYC

Before you start

The sign-and-send loop

1. Create the tokenized asset

2. Whitelist your investors

3. Mint tokens

4. Launch the offering

5. Take an investment

6. Close the offering

7. Let investors claim their tokens

8. Distribute dividends

When something fails

Doing this without writing HTTP

MCP server

Postman collection

​Before you start

​The sign-and-send loop

​1. Create the tokenized asset

​2. Whitelist your investors

​3. Mint tokens

​4. Launch the offering

​5. Take an investment

​6. Close the offering

​7. Let investors claim their tokens

​8. Distribute dividends

​When something fails

​Doing this without writing HTTP

MCP server

Postman collection

Before you start

The sign-and-send loop

1. Create the tokenized asset

2. Whitelist your investors

3. Mint tokens

4. Launch the offering

5. Take an investment

6. Close the offering

7. Let investors claim their tokens

8. Distribute dividends

When something fails

Doing this without writing HTTP