wallet-cli asset participate¶

Buy into a TRC10's ICO with TRX.

Synopsis¶

wallet-cli asset participate <asset> --pay <trx>
                             [--dry-run | (--sign-only | --build-only) [--expiration <ms>] | --wait [--wait-timeout <ms>]]
                             [--permission-id <n>] [options]

Description¶

Buys from a token's issuance inside its funding window, at the fixed rate set when it was issued. This is participation in the ICO, not a market trade — the tokens come out of the issuer's remaining supply, and the price is not negotiable. The issuer's address is resolved from the token, so there is nothing to pass for it.

--pay is the TRX you spend, not the tokens you receive. You get floor(pay × tokens ÷ trx) where trx:tokens is the token's issued rate — the amount paid times the unit price, rounded down, since the chain multiplies before dividing on integers. The TRX is transferred in full, so any truncated remainder is not refunded. What is lost is under one token minimal unit, and the chain stores that unit's price as the pair trxNum:num — trxNum sun buys num minimal units — so the discarded amount is under trxNum ÷ num sun. At --price 1:100 --precision 6 that is 0.01 sun, i.e. nothing; at --price 1:100 --precision 0 the pair reduces to 10000:1 and the worst case is 9,999 sun. If --pay is too small to buy even one unit, the command fails locally rather than broadcasting.

The acting account cannot be the token's own issuer.

By default the command returns at submission (stage: "submitted"), not confirmation — add --wait to block until confirmed/failed. Requires an account. The master password (via --password-stdin) is needed only by the modes that sign — --dry-run and --build-only do not unlock the wallet and run without it. Watch-only accounts fail with watch_only_no_signer in a signing mode.

The Ledger TRON app cannot sign TRC10 issuance contract types. Ledger accounts may dry-run or build unsigned hex, but signing modes fail with ledger_unsupported before device interaction.

Options¶

Option	Description
`<asset>`	Required. Token id or name; an all-digit value is read as the id
`--pay <trx>`	Required. TRX to spend (not a token count), > 0
`--dry-run`	Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only`
`--sign-only`	Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration`
`--build-only`	Build and estimate, output the unsigned hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration`
`--expiration <ms>`	Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s)
`--permission-id <n>`	Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0`
`--wait` / `--wait-timeout <ms>`	Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000)
`--password-stdin`	Master password from stdin (fd 0)

Plus the global options.

Examples¶

In the examples, $PW is your master password (from an environment variable, password manager, etc.), fed on stdin via --password-stdin.

Spend 100 TRX on a token issued at 1:100:

echo "$PW" | wallet-cli asset participate 1000124 --pay 100 --network tron:3448148188 --wait --password-stdin

✅ Participated in ICO
  Asset        BetaToken  (id 1000124)
  Issuer       TBeta9mR...8pLx
  Participant  TQkXm4vN...5Zt7Uw
  Paid         100 TRX
  Received     10,000 BetaToken
  TxID         4c8...
  Block        #57,883,402
  Fee          0 TRX
  Status       success

echo "$PW" | wallet-cli asset participate 1000124 --pay 100 --network tron:3448148188 --wait --password-stdin -o json

{"schema":"wallet-cli.result.v1","success":true,"command":"asset.participate","data":{"kind":"asset-participate","stage":"confirmed","txId":"4c8...","confirmed":true,"blockNumber":57883402,"feeSun":0,"netUsed":301,"netFeeSun":0,"failed":false,"assetId":"1000124","name":"BetaToken","issuerAddress":"TBeta9mR...","participantAddress":"TQkXm4vN...","paidSun":"100000000","receivedAmount":"10000000000","precision":6},"meta":{"durationMs":6450,"warnings":[]},"chain":{"family":"tron","network":"tron:3448148188","chainId":"3448148188"}}

Output¶

data varies by stage:

Stage	Fields
default (submit)	`kind: "asset-participate"`, `stage: "submitted"`, `txId`, `assetId`, `name`, `issuerAddress`, `participantAddress`, `paidSun`, `receivedAmount`
`--wait` (confirmed)	above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), and `failed`

paidSun is the TRX spent in sun; receivedAmount is the token amount in its smallest unit. Both are decimal strings; precision is included so text and machine consumers can scale the token amount.

Exit status¶

0 submitted (or built/signed in early-exit modes) · 1 execution failure (asset_not_found — no such token, not_in_ico_window — outside the funding window, self_participation — you issued this token, transaction_rejected — the node refused it, e.g. the balance cannot cover --pay, watch_only_no_signer, ledger_unsupported, auth_failed) · 2 usage error (missing_option — no --pay; invalid_amount — --pay is not a decimal number, or has more than 6 decimal places; invalid_value — --pay ≤ 0, or too small to buy one unit).