1  # ICP Agent Go Documentation
  2  
  3  Comprehensive documentation for the ICP Agent Go library.
  4  
  5  ## Overview
  6  
  7  This library provides Go bindings for the Internet Computer Protocol (ICP). It enables Go applications to interact with ICP canisters, manage identities, and perform operations on the ICP network.
  8  
  9  ## Quick Links
 10  
 11  - [API Reference](#api-reference) - Detailed module documentation
 12  - [Guides](#guides) - How-to tutorials
 13  - [Research](#research) - Feature research and specifications
 14  
 15  ## Installation
 16  
 17  ```bash
 18  go get icp-agent/internal/...
 19  ```
 20  
 21  ## Architecture
 22  
 23  ```
 24  identity          - Ed25519 identities, signing
 25  principal        - Principal types, derivation  
 26  agent            - HTTP client, query/update calls
 27  ledger          - Account IDs, transfer operations
 28  candid          - Candid encoding/decoding
 29  canister         - Canister operations
 30  certificate     - Certificate verification
 31  errors          - Error types
 32  ```
 33  
 34  ## API Reference
 35  
 36  ### Core Modules
 37  
 38  | Module | Description |
 39  |--------|-------------|
 40  | [identity](api/identity.md) | Ed25519 identities and signing |
 41  | [principal](api/principal.md) | Principal types and derivation |
 42  | [agent](api/agent.md) | HTTP client for ICP network |
 43  | [ledger](api/ledger.md) | Ledger operations and account IDs |
 44  | [candid](api/candid.md) | Candid encoding/decoding |
 45  | [canister](api/canister.md) | Canister call operations |
 46  | [certificate](api/certificate.md) | Certificate verification |
 47  | [errors](api/errors.md) | Error types and handling |
 48  
 49  ## Guides
 50  
 51  | Guide | Description |
 52  |-------|-------------|
 53  | [Agent Guide](guides/agent-guide.md) | Using the ICP agent |
 54  | [Canister Guide](guides/canister-guide.md) | Interacting with canisters |
 55  | [Getting Started](guides/getting-started.md) | Quick start tutorial |
 56  
 57  ## Research
 58  
 59  | Document | Description |
 60  |----------|-------------|
 61  | [Multi-Token Support](research/multi-token-support.md) | Supporting multiple token standards |
 62  | [Hardware Wallet](research/hardware-wallet-integration.md) | Hardware wallet integration |
 63  
 64  ## Common Use Cases
 65  
 66  ### Create Identity and Query Balance
 67  
 68  ```go
 69  // Create identity
 70  id, _ := identity.GenerateEd25519Identity()
 71  sender, _ := id.Sender()
 72  
 73  // Create agent
 74  a, _ := agent.NewAgentBuilder().
 75      WithURL("https://ic0.app").
 76      WithIdentity(id).
 77      Build()
 78  a.FetchRootKey()
 79  
 80  // Query balance
 81  result, _ := a.Query("ryjl3-tyaaa-aaaaa-aaaba-cai", "account_balance", args)
 82  ```
 83  
 84  ### Transfer ICP
 85  
 86  ```go
 87  // Create canister
 88  c, _ := canister.NewCanister("ryjl3-tyaaa-aaaaa-aaaba-cai", a)
 89  
 90  // Transfer
 91  result, _ := c.Method("transfer").
 92      WithArgs(to, amount, fee).
 93      Call()
 94  ```
 95  
 96  ## Error Handling
 97  
 98  ```go
 99  result, err := agent.Query(canisterID, method, args)
100  if err != nil {
101      if errors.Is(err, agent.ErrNoRootKey) {
102          // Fetch root key first
103      }
104      return err
105  }
106  ```
107  
108  ## Contributing
109  
110  When contributing:
111  
112  1. Follow existing code conventions
113  2. Write tests for new functionality
114  3. Update documentation
115  4. Keep API docs in sync with code
116  
117  ## License
118  
119  See project license for details.