Mutez ​

The type of amounts in SmartPy is sp.TMutez.

The corresponding type in Michelson is

Michelson mutez

Literals ​

sp.tez(<natural number>), sp.mutez(<natural number>)
Introduce a mutez.

Example ​

# Two identical amounts (one tez):
sp.tez(1)
sp.mutez(1000000)

Global properties ​

Get transferred amount ​

sp.amount
The amount of the current transaction, which is of type sp.TMutez.

Example ​

amount = sp.amount

Michelson AMOUNT

Get contract balance ​

sp.balance
The balance of the current contract.
Due to the not intuitive semantics in Michelson, we suggest that developers do not rely on balance too much.

See Tezos Agora Post.
In tests, a contract's balance is accessible through the <contract>.balance field.

Example ​

balance = sp.balance

Michelson BALANCE

Operations ​

Addition ​

expr1 + expr2
Add two values of type sp.TMutez, expr1 and expr2.

Example ​

result = sp.mutez(10) + sp.tez(1) # 1000010 of type sp.TMutez

Michelson ADD

Subtraction ​

expr1 - expr2
Subtract two values of type sp.TMutez, expr1 and expr2.
This operation fails if the result is negative.

Example ​

result = sp.mutez(20) - sp.mutez(10) # 10 of type sp.TMutez

sp.sub_mutez(expr1, expr2)
Subtract two values of type sp.TMutez, expr1 and expr2.
Returns a sp.TOption(sp.TMutez). This operation doesn't fail.

sp.sub_mutez(a, b) == sp.some(a-b) when a-b is a non negative and sp.none otherwise.

Example ​

result = sp.sub_mutez(sp.mutez(20) - sp.mutez(10)) # sp.some(sp.mutez(10))
result2 = sp.sub_mutez(sp.mutez(10) - sp.mutez(20)) # sp.none

Michelson SUB

Multiplication ​

sp.mul(<expr1>, <expr2>)
Multiply a sp.TMutez with a sp.TNat and produce a sp.TMutez.

Example ​

value = sp.mul(sp.nat(2), sp.mutez(2)) # 4 of type sp.TMutez

Division ​

sp.ediv(expr1, expr2)
Perform euclidean division, where expr1 is the dividend, and expr2 is the divisor.

• When expr1 and expr2 are both of type sp.TMutez, the returned value is of type sp.TOption(sp.TPair(sp.TNat, sp.TMutez)).

• When expr1 is of type sp.TMutez and expr2 is of type sp.TNat, the returned value is of type sp.TOption(sp.TPair(sp.TMutez, sp.TMutez)).

Example ​

(quotient, remainder) = sp.match_pair(sp.ediv(sp.tez(11), sp.tez(2)).open_some())

Michelson EDIV

Split tokens ​

sp.split_tokens(amount, quantity, totalQuantity)
Compute amount * quantity / totalQuantity where amount is of type sp.TMutez, quantity and totalQuantity are of type sp.TNat.

Example ​

sp.split_tokens(sp.mutez(100), 1, 10) # 10 mutez