Skip to main content

Contract Invoke: Argument Types

When using stellar contract invoke, each --arg-name <value> flag is parsed according to the contract's type spec. This guide shows the correct format for each supported type.

Integers (u32, i32, u64, i64)​

Pass bare numeric literals directly on the command line.

stellar contract invoke --id mycontract -- my_function \
    --count 42 \
    --offset -7

Large Integers (u128, i128, u256, i256)​

Pass bare numeric literals, just like small integers. The CLI reads the raw value as a string internally, bypassing JSON number precision limits entirely.

stellar contract invoke --id mycontract -- my_function \
    --amount 340282366920938463463374607431768211455

Boolean​

Pass true or false as unquoted literals.

stellar contract invoke --id mycontract -- my_function \
    --is_active true \
    --is_paused false

String​

Bare words work for simple strings. Numbers and booleans are also accepted and are automatically converted to their string representation, so you do not need to add extra quoting. Explicit JSON quoting is also accepted.

# Bare word
stellar contract invoke --id mycontract -- my_function \
    --label hello

# Number auto-converted to string "42"
stellar contract invoke --id mycontract -- my_function \
    --label 42

# Boolean auto-converted to string "true"
stellar contract invoke --id mycontract -- my_function \
    --label true

# Explicitly quoted JSON string
stellar contract invoke --id mycontract -- my_function \
    --label '"hello world"'

Symbol​

Symbols follow the same rules as String: bare words, numbers, and booleans are all accepted, and non-string JSON values are auto-converted.

stellar contract invoke --id mycontract -- my_function \
    --status active

Address​

You can pass either a locally known identity name (e.g. alice) or a raw Stellar strkey (G… for accounts, C… for contracts).

# Using an identity alias
stellar contract invoke --id mycontract -- my_function \
    --owner alice

# Using a raw strkey
stellar contract invoke --id mycontract -- my_function \
    --owner GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN

Bytes / BytesN​

Pass a hex-encoded string representing the byte sequence.

stellar contract invoke --id mycontract -- my_function \
    --hash "deadbeef01020304"

Optional Arguments​

Simply omit the flag. The CLI will supply a void / null value for any Option<T> parameter that is not provided.

# If `--memo` is optional, leaving it out passes None
stellar contract invoke --id mycontract -- my_function \
    --amount 100

Vec​

Pass a JSON array, quoting the whole value so the shell does not split it.

stellar contract invoke --id mycontract -- my_function \
    --recipients '["alice", "bob", "carol"]'

Map​

Pass a JSON object with string keys.

stellar contract invoke --id mycontract -- my_function \
    --metadata '{"key": "value", "version": "1"}'

Tuple​

Pass a JSON array whose elements match the tuple's field order.

stellar contract invoke --id mycontract -- my_function \
    --point '[10, 20]'

Struct (User-Defined Type)​

Pass a JSON object with the struct's named fields.

stellar contract invoke --id mycontract -- my_function \
    --config '{"max_supply": "1000000", "decimals": 7}'

Enum / Union (User-Defined Type)​

For unit variants, pass the variant name as a plain string. For variants that carry a value, pass a JSON object with the variant name as the key.

# Unit variant
stellar contract invoke --id mycontract -- my_function \
    --status "Active"

# Variant with a value
stellar contract invoke --id mycontract -- my_function \
    --result '{"Ok": 42}'

File-Based Arguments​

For long or complex JSON values, use the --arg-file-path flag variant to load the value from a file instead of inlining it on the command line. The flag name is derived from the argument name by appending -file-path.

# Write the JSON to a file first
echo '{"max_supply": "1000000", "decimals": 7}' > config.json

# Then reference the file
stellar contract invoke --id mycontract -- my_function \
    --config-file-path config.json

For Bytes and BytesN parameters, the file's raw binary content is read directly — no hex encoding is required.

stellar contract invoke --id mycontract -- my_function \
    --hash-file-path /path/to/binary.bin

Guides in this category: