> For the complete documentation index, see [llms.txt](https://docs.trac.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trac.network/documentation/developers/mainnet/wallet-api.md).

# Wallet API

The API is designed for dApps to:

* Connect to the user’s wallet
* Read identity + balance
* Sign messages
* Construct/sign/push Trac Network (TNK) transfers
* Sign Trac **contract** transactions (for `trac-peer`)

This page is based on the reference implementation in `tap-wallet-extension` (main branch) in this workspace.

### Conventions

* All methods are async and return Promises.
* Hex strings are lowercase/uppercase tolerant unless stated otherwise.
* Addresses are bech32m strings with `trac1...` prefix.
* Amounts/balances are returned as strings (typically smallest-unit / integer strings).

### Methods

#### `tracnetwork.requestAccount()`

Connects the wallet and returns the connected address.

* Params: none
* Returns: `Promise<string>` (wallet address)

```js
const address = await window.tracnetwork.requestAccount();
```

Example response:

```txt
trac1wnky35sgxefesuja46yvyf3tmf7pneeqv3ns5pk5pjlzu082f23s4r7923
```

#### `tracnetwork.getAddress()`

Returns the currently connected address.

* Params: none
* Returns: `Promise<string>` (wallet address)

```js
const address = await window.tracnetwork.getAddress();
```

#### `tracnetwork.getBalance()`

Returns the TNK balance of the connected account.

* Params: none
* Returns: `Promise<string>` (balance)

```js
const balance = await window.tracnetwork.getBalance();
```

Example response:

```txt
938000000000000000
```

#### `tracnetwork.getNetwork()`

Returns the current wallet network.

* Params: none
* Returns: `Promise<string>` (typically `"livenet"` or `"testnet"`)

```js
const network = await window.tracnetwork.getNetwork();
```

#### `tracnetwork.switchNetwork(network)`

Switches wallet network.

* Params:
  * `network: string` (accepted values include `"livenet"`, `"mainnet"`, `"testnet"`)
* Returns: `Promise<string>` (network name, e.g. `"testnet"`)

```js
await window.tracnetwork.switchNetwork("testnet");
```

Example response:

```txt
testnet
```

#### `tracnetwork.getPublicKey()`

Returns the connected wallet public key (hex).

* Params: none
* Returns: `Promise<string>` (public key hex, 32 bytes / 64 hex chars)

```js
const pubKey = await window.tracnetwork.getPublicKey();
```

Example response:

```txt
74ec48d208365398725dae88c2262bda7c19e72064670a06d40cbe2e3cea4aa3
```

#### `tracnetwork.signMessage(message)`

Signs an arbitrary message.

* Params:
  * `message: string`
* Returns: `Promise<{ signature: string, publicKey: string, address: string }>`

```js
const sig = await window.tracnetwork.signMessage("hello");
```

Example response shape:

```json
{
  "signature": "<hex-signature>",
  "publicKey": "<hex-publicKey>",
  "address": "trac1..."
}
```

Notes:

* Signing semantics are wallet-implementation-defined (what bytes are signed).
* When using this for a protocol that verifies signatures, ensure the verifier uses the same message bytes the wallet signed.

#### `tracnetwork.sendTNK(from, to, amount)`

Transfers TNK (high-level helper).

* Params:
  * `from: string`
  * `to: string`
  * `amount: string | number`
* Returns: `Promise<{ txHash: string, success: boolean }>`

```js
const res = await window.tracnetwork.sendTNK(fromAddress, toAddress, "1");
```

Example response:

```json
{
  "txHash": "6f7d901d63405873f3e845858b213603762bc4a1846a3f197a5a85092f84dd73",
  "success": true
}
```

#### `tracnetwork.buildTracTx({ from?, to, amount })`

Builds **and signs** a Trac Network TNK transfer and returns a broadcastable payload (base64 string).

* Params:
  * `{ from?: string, to: string, amount: string | number }`
* Returns: `Promise<string>` (`txPayload`, base64)

```js
const txPayload = await window.tracnetwork.buildTracTx({ to: recipient, amount: "1" });
```

#### `tracnetwork.pushTracTx(txPayload)`

Pushes a signed Trac Network transfer transaction payload (from `buildTracTx`) to the network.

* Params:
  * `txPayload: string` (base64)
* Returns: `Promise<{ txHash: string, success: boolean }>`

```js
const result = await window.tracnetwork.pushTracTx(txPayload);
```

Example response:

```json
{
  "txHash": "c3ce135ccc8e5d27b1b9ed153b05fada9937c5bf07085c4dbde601cb763f33e4",
  "success": true
}
```

#### `tracnetwork.signTracTx(contractTx)`

Signs a **contract transaction** (used with `trac-peer` contract RPC flows).

* Params:
  * `contractTx: { prepared_command: object, nonce: string, context: object }`
* Returns: `Promise<{ tx: string, signature: string }>`

Minimal example (shape):

```json
{
  "prepared_command": { "type": "catch", "value": {} },
  "nonce": "<hex32>",
  "context": {
    "networkId": 918,
    "txv": "<hex32>",
    "iw": "<hex32>",
    "bs": "<hex32 | optional>",
    "mbs": "<hex32>"
  }
}
```

Return value:

```json
{
  "tx": "<hex32>",
  "signature": "<hex64>"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.trac.network/documentation/developers/mainnet/wallet-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.