Skip to main content
POST
Prepare an STO investment
Prepares unsigned transactions for making an investment in a Security Token Offering (STO). Use POST /prepare-transactions with method=newInvest. The prepared transaction is signed and sent by investorAddress, not by the tokenizer.

Prerequisites

newInvest prepares a single buyToken transaction and nothing else. It does not whitelist the investor and it does not return an approve transaction. Everything below must already be true before you call it.
1

The investor exists, with a wallet address

Create the investor with whitelist or create-kyc-link, passing the wallet address. Verify with GET /get-investor-info: a null walletAddress fails the call.The investor’s email must be different from the tokenizer account’s email, or no investor record is created and lookups return Investor not found.
2

The investor's wallet is whitelisted for this token

Confirm with GET /get-whitelist-status?tokenSymbol=…&address=…. Whitelisting is per token, and the whitelist transaction must be signed, sent, and confirmed — preparing it is not enough.
3

KYC is approved, or not required

GET /get-investor-infocomplianceStatus must be APPROVED or NOT_REQUIRED. In Sandbox, create the investor with needKyc: false and it reads NOT_REQUIRED from the start.
4

The investor approved this offering's escrow

Use approve with the offering’s escrowAddress as spenderAddress. Allowances are per spender: approving one offering’s escrow grants nothing to another’s.
5

The investor holds enough payment token

An allowance is a permission, not a balance. Both must cover the investment amount.
6

The offering is open

startDate must have passed and endDate must not have. Check with GET /get-sto-by-id.
The amount must also sit within the offering’s minInvestment and maxInvestment.
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.

How failures surface

The whitelist, the allowance, and the balance are enforced by the contract, not by an API precondition check — they are caught when the API simulates the transaction. So they come back as contract reverts, not as friendly messages:
Compliance is checked before the chain is simulated, so a KYC-ineligible investor always gets a plain 400 naming the compliance problem. A revert therefore always means chain state — a timestamp, a whitelist entry, an allowance, or a balance — never a compliance verdict.

Next step

Preparing does not touch the chain. The response gives you txId and an array of unsigned transactions — you still have to sign and submit them.
1

Sign every returned transaction

Sign each entry locally with the wallet that sends the transaction — signerAddress, or investorAddress for newInvest and claimTokens. It must be whitelisted by Brickken, and it needs native gas on the target chain.
2

Submit the signed payloads

POST them to /send-transactions as { txId, signedTransactions } and Brickken broadcasts for you.If you would rather broadcast yourself, prepare with executionMode: "client-broadcast" and confirm afterwards with { txId, txHash } instead.
3

Poll until it confirms

Call GET /get-transaction-status with the txId. A pending status means it is broadcast but not yet mined — do not resubmit.
Full walkthrough: Tokenize an asset and run an STO. See Troubleshooting for full revert decoding.

Authorizations

x-api-key
string
header
required

Body

application/json
method
enum<string>
default:newInvest
required

Required. Operation to prepare. Must be newInvest for this endpoint.

Available options:
newInvest
Example:

"newInvest"

chainId
string
required

Required. Blockchain network identifier. Hex format is recommended, for example Sepolia aa36a7.

Example:

"aa36a7"

investorAddress
string
required

Required. Investor wallet address. It is used as the signer and sender of the prepared transaction, and must already be whitelisted for the token and hold both the payment-token balance and an allowance towards the offering's escrow.

Pattern: ^0x[a-fA-F0-9]{40}$
Example:

"0x1111111111111111111111111111111111111111"

investorEmail
string<email>
required

Required. Email of the investor. The investor must already exist in Brickken with a wallet address on record, and must be KYC eligible: complianceStatus from GET /get-investor-info has to be APPROVED or NOT_REQUIRED. The email must differ from the tokenizer account's email, otherwise no investor record exists and the call returns Investor not found.

Example:

"investor@example.com"

tokenSymbol
string
required

Required. Symbol of the token being offered.

Example:

"EXMPL"

investmentAmount
string
required

Required. Payment-token amount to invest. It must fall within the offering's minimum and maximum investment. An amount above the wallet's balance, or above its allowance towards the escrow, reverts with Solidity panic 0x11.

Example:

"1000"

signerAddress
string

Optional and ignored for this method. The prepared transactions are always signed and sent by investorAddress.

Example:

"0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

paymentTokenSymbol
string

Optional. Symbol of the payment token used for the investment. If omitted, the chain default payment token is used.

Example:

"USDT"

Response

200 - application/json

Successful response

transactions
object[]
required

Array of unsigned transaction objects ready for signing

txId
string
required

Unique identifier for this transaction batch (required for /send-transactions). This is NOT a blockchain transaction hash.

Example:

"0x46adea7bdf49c576a760102e0d6bc9ecd650b3998588cd3d7f576a7973426aad"

info
object

Metadata about the operation