Aptos Agent

Aptos Claude Agent

Aptos blockchain interaction with game-theoretic decision analysis.

When to Use

• Check APT wallet balances
• Transfer APT tokens
• Swap tokens on DEX (Liquidswap, etc.)
• Stake APT
• Call Move view functions
• Process natural language blockchain intents
• Query NFT/token collections
• Interact with multisig accounts

Setup

MCP server configured in ~/.mcp.json:

{
  "aptos": {
    "command": "node",
    "args": ["/path/to/aptos-claude-agent/dist/mcp/server.js"],
    "env": {
      "APTOS_NETWORK": "mainnet",
      "APTOS_PRIVATE_KEY": "${APTOS_PRIVATE_KEY}"
    }
  }
}

Available MCP Tools

Security Model

1. Simulation First: All transactions simulated before execution
2. Approval Required: Every state-changing operation needs explicit approval
3. Game-Theoretic Analysis: Transactions modeled as open games
4. Wallet Validation: ALWAYS validate key→address before funding

CRITICAL: Wallet Derivation Safety

NEVER use derive-resource-account-address for wallet creation.

Correct Workflow

# 1. Generate key
aptos key generate --output-file my_key

# 2. Derive address FROM PRIVATE KEY
aptos init --private-key-file my_key --network mainnet --profile my_wallet

# 3. VALIDATE before funding
just aptos-validate "PRIVATE_KEY" "EXPECTED_ADDRESS"

# 4. Only fund AFTER validation passes

What Can Go Wrong

• Using derive-resource-account-address with pubkey = PERMANENT FUND LOSS
• Resource accounts need signer capabilities from source account
• If key doesn't match address, funds are unrecoverable

Validation

Run just aptos-validate-all to verify all configured wallets before any funding operation.

Aptos Framework Reference (0x1)

Core Modules

0x1::coin Module

Key Structs:

• Coin<CoinType> - Fungible token container
• CoinStore<CoinType> - Account balance storage
• CoinInfo<CoinType> - Token metadata
• MintCapability<CoinType> - Minting rights
• BurnCapability<CoinType> - Burning rights
• FreezeCapability<CoinType> - Freeze rights

View Functions:

0x1::coin::balance<CoinType>(owner: address): u64
0x1::coin::is_account_registered<CoinType>(account: address): bool
0x1::coin::name<CoinType>(): vector<u8>
0x1::coin::symbol<CoinType>(): vector<u8>
0x1::coin::decimals<CoinType>(): u8
0x1::coin::supply<CoinType>(): Option<u128>

Entry Functions:

0x1::coin::transfer<CoinType>(from: &signer, to: address, amount: u64)
0x1::coin::register<CoinType>(account: &signer)

0x1::fungible_asset Module

Key Structs:

• Metadata - Asset metadata object
• FungibleStore - Balance storage
• FungibleAsset - Asset container
• MintRef, BurnRef, TransferRef - Capabilities

View Functions:

0x1::fungible_asset::balance<T>(store: Object<T>): u64
0x1::primary_fungible_store::balance(account: address, metadata: Object<Metadata>): u64

0x1::stake Module

Key Structs:

• StakePool - Validator stake pool
• ValidatorConfig - Validator configuration
• OwnerCapability - Pool ownership

View Functions:

0x1::stake::get_validator_state(pool_address: address): u64
0x1::stake::get_stake(pool_address: address): (u64, u64, u64, u64)

0x1::delegation_pool Module

View Functions:

0x1::delegation_pool::get_stake(pool_address: address, delegator: address): (u64, u64, u64)
0x1::delegation_pool::calculate_and_update_voter_total_voting_power(pool_address: address): u64

0x1::multisig_account Module

Key Functions:

0x1::multisig_account::create(owner: &signer, num_signatures_required: u64, owners: vector<address>)
0x1::multisig_account::create_transaction(multisig: address, payload: vector<u8>)
0x1::multisig_account::approve_transaction(owner: &signer, multisig: address, sequence_number: u64)
0x1::multisig_account::execute_transaction(multisig: address, sequence_number: u64)

Token Standards Reference

Legacy Token (0x3::token)

Key Structs:

• Token - Token instance with id, amount, properties
• TokenId - Global unique identifier (creator + collection + name + version)
• TokenData - Shared metadata (max supply, uri, royalty)
• TokenStore - Account's token holdings
• CollectionData - Collection metadata
• Royalty - Royalty configuration

Entry Functions:

0x3::token::create_collection_script(creator: &signer, name: String, description: String, uri: String, maximum: u64)
0x3::token::create_token_script(creator: &signer, collection: String, name: String, description: String, ...)
0x3::token::mint_script(creator: &signer, token_data_address: address, collection: String, name: String, amount: u64)
0x3::token::direct_transfer_script(sender: &signer, receiver: &signer, creators_address: address, ...)

View Functions:

0x3::token::balance_of(owner: address, id: TokenId): u64
0x3::token::get_royalty(token_data_id: TokenDataId): Royalty
0x3::token::get_token_supply(creator: address, collection: String, name: String): Option<u64>

Digital Asset (0x4::token + 0x4::aptos_token)

Key Structs (0x4::token):

• Token - Object-based token with collection, index, description, name
• BurnRef - Burning capability
• MutatorRef - Mutation capability

Key Structs (0x4::aptos_token):

• AptosCollection - No-code collection with mutability settings
• AptosToken - Minimally viable token

Entry Functions:

0x4::aptos_token::create_collection(creator: &signer, description: String, name: String, uri: String, ...)
0x4::aptos_token::mint(creator: &signer, collection: String, description: String, name: String, uri: String, ...)
0x4::aptos_token::mint_token_object(creator: &signer, collection: String, ...) -> Object<AptosToken>
0x4::aptos_token::burn(owner: &signer, token: Object<AptosToken>)
0x4::aptos_token::freeze_transfer(creator: &signer, token: Object<AptosToken>)
0x4::aptos_token::set_description(creator: &signer, token: Object<AptosToken>, description: String)

View Functions:

0x4::token::creator(token: Object<Token>): address
0x4::token::collection_name(token: Object<Token>): String
0x4::aptos_token::are_properties_mutable(token: Object<AptosToken>): bool
0x4::aptos_token::is_burnable(token: Object<AptosToken>): bool

Supporting Modules

0x4::collection:

0x4::collection::count(collection: Object<Collection>): Option<u64>
0x4::collection::creator(collection: Object<Collection>): address
0x4::collection::name(collection: Object<Collection>): String

0x4::royalty:

0x4::royalty::get(token: Object<Token>): Option<Royalty>
0x4::royalty::payee_address(royalty: &Royalty): address
0x4::royalty::numerator(royalty: &Royalty): u64
0x4::royalty::denominator(royalty: &Royalty): u64

0x4::property_map:

0x4::property_map::read_string(object: &Object<T>, key: &String): String
0x4::property_map::read_u64(object: &Object<T>, key: &String): u64
0x4::property_map::read_bool(object: &Object<T>, key: &String): bool

Common View Function Patterns

Check APT Balance

aptos_view(
  functionId: "0x1::coin::balance",
  typeArgs: ["0x1::aptos_coin::AptosCoin"],
  args: ["0xADDRESS"]
)

Check Token Balance (Legacy)

aptos_view(
  functionId: "0x3::token::balance_of",
  typeArgs: [],
  args: ["0xOWNER", { token_data_id: {...}, property_version: 0 }]
)

Check Stake

aptos_view(
  functionId: "0x1::stake::get_stake",
  typeArgs: [],
  args: ["0xVALIDATOR_POOL"]
)

Check Delegation

aptos_view(
  functionId: "0x1::delegation_pool::get_stake",
  typeArgs: [],
  args: ["0xPOOL", "0xDELEGATOR"]
)

Game-Theoretic Features

Nashator Analysis

Computes deviation incentives for transactions:

• LAX monoidal (fire): Actual execution
• STRONG monoidal (exec): Simulation only

Bisimulation Self-Play

Explores alternatives via attacker/defender games. Equilibrium detected when |utility - quality| < 0.15.

Risk Visualization

Decisions map to colors via deterministic LCG:

• HOT ZONE [160-220]: High-risk indices

DeFi Protocols on Aptos

Related Skills

• aptos-trading - Alpha executor trading scripts
• acsets-algebraic-databases - ACSet schemas for Aptos data
• asi-integrated - Unified ASI skill orchestration