Merge pull request #3669 from dfinity/checking-cycles-bal

add: check cycles balance programmatically

docs/developer-docs/smart-contracts/topping-up/topping-up-canister.mdx

@@ -1,5 +1,9 @@
 import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
+import TabItem from "@theme/TabItem";
+import useBaseUrl from "@docusaurus/useBaseUrl";
+import { AdornedTabs } from "/src/components/Tabs/AdornedTabs";
+import { AdornedTab } from "/src/components/Tabs/AdornedTab";
 
 # Topping up a canister
 
@@ -63,6 +67,37 @@ Balance: 9_811_813_913_485 Cycles
 Module hash: 0xe7866e1949e3688a78d8d29bd63e1c13cd6bfb8fbe29444fa606a20e0b1e33f0
 ```
 
+Canisters can check their own balance programmatically. For example:
+
+<AdornedTabs groupId="language">
+<TabItem value="motoko" label="Motoko" default>
+
+Motoko canisters can use the [ExperimentalCycles library](/docs/current/motoko/main/base/ExperimentalCycles) to interact with cycles:
+
+``` motoko no-repl
+import Cycles "mo:base/ExperimentalCycles";
+import Debug "mo:base/Debug";
+
+actor {
+  public func main() : async() {
+    Debug.print("Main balance: " # debug_show(Cycles.balance()));
+  };
+}
+```
+
+</TabItem>
+
+<TabItem value="rust" label="Rust">
+
+Rust canisters can use the function `canister_balance128()` from the [Rust IC CDK](https://docs.rs/ic-cdk/latest/ic_cdk/api/fn.canister_balance128.html):
+
+```rust
+let current_canister_balance = ic_cdk::api::canister_balance();
+```
+
+</TabItem>
+</AdornedTabs>
+
 ### Option 1: If you have ICP on your account
 
 If you have ICP on the account associated with a `dfx` identity, you can tell the ledger canister to take some of that ICP, convert it to cycles, and give it to a canister of your choice using the command `dfx ledger top-up --icp <AMOUNT> <DESTINATION> --network ic`:
@@ -154,4 +189,4 @@ Freezing threshold: 3_472_000
 Memory Size: Nat(2363181)
 Balance: 3_100_000_000_000 Cycles
 Module hash: 0xf8680eb74022a1079012b7e9c644d1156580002a6126305791811533d3fd6f17
-```
+```