Contract Invoke: Argument Types - Stellar Developer Docs

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.

cookbooktest.ignore

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.

cookbooktest.ignore

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

Boolean

Pass true or false as unquoted literals.

cookbooktest.ignore

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.

cookbooktest.ignore

# 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.

cookbooktest.ignore

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).

cookbooktest.ignore

# 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.

cookbooktest.ignore

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.

cookbooktest.ignore

# 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.

cookbooktest.ignore

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

Map

Pass a JSON object with string keys.

cookbooktest.ignore

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.

cookbooktest.ignore

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

Struct (User-Defined Type)

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

cookbooktest.ignore

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.

cookbooktest.ignore

# 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.

cookbooktest.ignore

# 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.

cookbooktest.ignore

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

​Integers (u32, i32, u64, i64)

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

​Boolean

​String

​Symbol

​Address

​Bytes / BytesN

​Optional Arguments

​Vec

​Map

​Tuple

​Struct (User-Defined Type)

​Enum / Union (User-Defined Type)

​File-Based Arguments

Integers (`u32`, `i32`, `u64`, `i64`)

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

Boolean

String

Symbol

Address

Bytes / BytesN

Optional Arguments

Vec

Map

Tuple

Struct (User-Defined Type)

Enum / Union (User-Defined Type)

File-Based Arguments