Skip to main content
Agent instructions

Execute sequentially. When a step asks the human a question, STOP and wait for their response before continuing.

dfx

For CLI exploration, trading bots, and Node.js engines that trade with a dfx identity.

1. dfx​

dfx --version
Agent instructions

If dfx --version fails (command not found), do NOT continue. Display this exact message and STOP:

dfx is not installed yet. This is the one interruption in setup — after this, everything is automatic.

  1. Paste this into your terminal: 
    sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
  2. Close this terminal and open a new one (the installer updates your shell profile, so the current session won't see dfx).
  3. Start a new agent session and run: 
    read docs.partyhats.xyz/agents/trading/dfx

That's it — setup will pick up right here and fly through the rest.

Do NOT attempt to install dfx yourself. Do NOT run source ~/.bashrc or similar — a fresh terminal is the only reliable path. After printing the message above, STOP. Do not proceed to step 2.

2. Identity​

Agent instructions
  • Never run dfx identity new — private keys must not pass through agent context.
  • If the current identity is default, stop and ask the human to switch to (or create) a dedicated identity themselves.
  • On failure, stop and explain.
dfx identity whoami

Then retrieve the principal and account ID for the active identity:

dfx identity get-principal
dfx ledger account-id
  • Principal (xxxxx-xxxxx-xxxxx-xxxxx-cai) — your identifier on every canister. Used for all ICRC calls and canister interactions.
  • Account ID (64-char hex) — the deposit address. This is where the human sends tokens to fund the agent. Centralized exchanges and the NNS use this format.

3. ICP Balance​

Agent instructions

If balance is 0, display the account ID from step 2 and ask the human if they want to practice depositing tokens before continuing.

All canister calls target mainnet with --ic. Try your first one:

PRINCIPAL=$(dfx identity get-principal)

dfx canister call --ic ryjl3-tyaaa-aaaaa-aaaba-cai icrc1_balance_of \
  "(record { owner = principal \"$PRINCIPAL\"; subaccount = null })"

This is the ICP ledger (ryjl3-tyaaa-aaaaa-aaaba-cai). The same icrc1_balance_of pattern works for every token — only the canister ID changes. Use get_routing_state() on any spot canister to get its token ledger principals, decimals, and fees.

4. Prior Activity​

dfx canister call --ic gx3we-baaaa-aaaab-afaia-cai get_user_markets '()'

Non-empty result means this principal has traded before.

Complete Flow: First Trade​

A full dfx session — discover a market, read state, approve, deposit, and place a limit buy.

5. Discover Market​

# Find the ckBTC/ckUSDT spot canister
dfx canister call --ic gx3we-baaaa-aaaab-afaia-cai get_market_by_symbols '("ckBTC", "ckUSDT")'
# → (opt principal "...")  — this is your SPOT_CANISTER

Save the returned principal:

SPOT=<paste-principal-here>

6. Read Market State​

dfx canister call --ic $SPOT get_routing_state '()'

From the output, note:

  • reference_tick — current price as a tick
  • quote.ledger — the ckUSDT ledger principal
  • quote.fee — ledger transfer fee (needed for approve amount)
  • quote.decimals — token decimals (6 for ckUSDT)
QUOTE_LEDGER=<quote-ledger-principal>

7. ICRC-2 Approve + Deposit​

# Approve the spot canister to pull ckUSDT from your wallet
dfx canister call --ic $QUOTE_LEDGER icrc2_approve "(record {
  spender = record { owner = principal \"$SPOT\"; subaccount = null };
  amount = 10_000_000 : nat;
  fee = null; memo = null; from_subaccount = null;
  created_at_time = null; expected_allowance = null; expires_at = null;
})"

# Deposit into trading balance
dfx canister call --ic $SPOT deposit '(variant { quote }, 9_000_000 : nat)'

8. Quote + Place Order​

# Quote a buy — spending 5 ckUSDT, 50 bps slippage
dfx canister call --ic $SPOT quote_order \
  '(variant { buy }, 5_000_000 : nat, opt (-230_000 : int32), opt (50 : nat32))'

The response includes pool_swaps and book_order. For a simple limit order:

# Place a resting limit buy at a specific tick
dfx canister call --ic $SPOT create_orders '(
  vec {},
  vec { record {
    side = variant { buy };
    input_amount = 5_000_000 : nat;
    limit_tick = -230_500 : int32;
    immediate_or_cancel = false;
  } },
  vec {}
)'

9. Check + Withdraw​

# Check your state
dfx canister call --ic $SPOT get_user '()'

# Withdraw base tokens back to wallet
dfx canister call --ic $SPOT withdraw '(variant { base }, 100_000 : nat)'
Candid Syntax
  • Variants: variant { buy } or variant { quote }
  • Optionals: null for absent, opt (50 : nat32) for present
  • Type annotations: use : nat, : int32, : nat32 on literals
  • Records: record { field = value; ... } with semicolons
  • Vectors: vec { item1; item2 } or vec {} for empty

dfx Documentation​

For more on dfx (identity management, canister deployment, cycles, local development), see the official dfx documentation.