> For the complete documentation index, see [llms.txt](https://docs.ama.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ama.one/sdk/5.-api-modules.md).

# 5. API Modules

Complete reference for all API modules in the Amadeus Protocol SDK.

### Overview

The SDK provides access to various API modules through the `AmadeusSDK` instance:

```typescript
import { AmadeusSDK } from '@amadeus-protocol/sdk'

const sdk = new AmadeusSDK()

// Access API modules
sdk.chain // Chain API
sdk.wallet // Wallet API
sdk.transaction // Transaction API
sdk.contract // Contract API
sdk.epoch // Epoch API
sdk.peer // Peer API
sdk.proof // Proof API
```

### Chain API

Query blockchain data including chain tip, statistics, entries, and transaction events.

#### `getTip()`

Get the current chain tip (latest entry).

```typescript
const { entry } = await sdk.chain.getTip()

console.log('Height:', entry.height)
console.log('Hash:', entry.hash)
console.log('Timestamp:', entry.timestamp)
```

**Returns**: `Promise<GetTipResponse>` with chain entry

#### `getStats()`

Get chain statistics.

```typescript
const { stats } = await sdk.chain.getStats()

console.log('Total entries:', stats.total_entries)
console.log('Total transactions:', stats.total_transactions)
console.log('Current height:', stats.height)
console.log('Circulating supply:', stats.circulating)
```

**Returns**: `Promise<GetStatsResponse>` with chain statistics

#### `getByHeight(height: number)`

Get entries at a specific height.

```typescript
const { entries } = await sdk.chain.getByHeight(1000)

entries.forEach((entry) => {
	console.log('Entry hash:', entry.hash)
	console.log('Height:', entry.height)
})
```

**Parameters**:

* `height` (number): Chain height

**Returns**: `Promise<GetByHeightResponse>` with array of entries

#### `getByHash(hash: string)`

Get entries by hash.

```typescript
const { entry } = await sdk.chain.getByHash('5Kd3N...')

console.log('Entry:', entry)
```

**Parameters**:

* `hash` (string): Entry hash (Base58 encoded)

**Returns**: `Promise<GetByHashResponse>` with chain entry

#### `getTransactionEventsByAccount(address: string, filters?: TransactionFilters)`

Get transaction events for an account.

```typescript
const events = await sdk.chain.getTransactionEventsByAccount('5Kd3N...', {
	limit: 10,
	sort: 'desc',
	type: 'sent' // or 'recv'
})

events.txs.forEach((event) => {
	console.log('Type:', event.type)
	console.log('Amount:', event.amount)
	console.log('Symbol:', event.symbol)
	console.log('Timestamp:', event.timestamp)
})
```

**Parameters**:

* `address` (string): Account address (Base58 encoded)
* `filters` (optional): Transaction filters

**Returns**: `Promise<GetTransactionEventsByAccountResponse>` with transaction events

### Wallet API

Query wallet balances and transaction information.

#### `getBalance(address: string, symbol?: string)`

Get balance for a specific address and token symbol.

```typescript
const balance = await sdk.wallet.getBalance('5Kd3N...', 'AMA')

console.log('Balance (float):', balance.balance.float)
console.log('Balance (flat):', balance.balance.flat)
console.log('Symbol:', balance.balance.symbol)
```

**Parameters**:

* `address` (string): Wallet address (Base58 encoded)
* `symbol` (string, optional): Token symbol (default: 'AMA')

**Returns**: `Promise<WalletBalance>` with token balance

#### `getAllBalances(address: string)`

Get all token balances for an address.

```typescript
const { balances } = await sdk.wallet.getAllBalances('5Kd3N...')

Object.entries(balances).forEach(([symbol, balance]) => {
	console.log(`${symbol}: ${balance.float}`)
})
```

**Parameters**:

* `address` (string): Wallet address (Base58 encoded)

**Returns**: `Promise<GetAllBalancesResponse>` with all balances

#### `getTransactions(address: string, query?: GetWalletTransactionsQuery)`

Get transactions for a wallet address.

```typescript
const { txs, cursor } = await sdk.wallet.getTransactions('5Kd3N...', {
	limit: 10,
	sort: 'desc',
	contract: 'Coin',
	function: 'transfer'
})

txs.forEach((tx) => {
	console.log('Hash:', tx.hash)
	console.log('Action:', tx.tx.action)
})
```

**Parameters**:

* `address` (string): Wallet address (Base58 encoded)
* `query` (optional): Query parameters (limit, sort, contract, function, type, cursor)

**Returns**: `Promise<GetWalletTransactionsResponse>` with transactions and cursor

### Transaction API

Submit transactions and query transaction data.

#### `submit(txPacked: Uint8Array | string)`

Submit a transaction to the network.

```typescript
const result = await sdk.transaction.submit(txPacked)

if (result.error === 'ok') {
	console.log('Transaction hash:', result.hash)
} else {
	console.error('Error:', result.error)
}
```

**Parameters**:

* `txPacked` (Uint8Array | string): Packed transaction as Uint8Array or Base58 string

**Returns**: `Promise<SubmitTransactionResponse>` with submission result

#### `submitAndWait(txPacked: Uint8Array | string)`

Submit a transaction and wait for confirmation.

```typescript
try {
	const result = await sdk.transaction.submitAndWait(txPacked)

	if (result.error === 'ok') {
		console.log('Hash:', result.hash)
		console.log('Entry hash:', result.metadata?.entry_hash)
		console.log('Receipt:', result.receipt)
	}
} catch (error) {
	console.error('Transaction failed or timed out:', error)
}
```

**Parameters**:

* `txPacked` (Uint8Array | string): Packed transaction

**Returns**: `Promise<SubmitAndWaitTransactionResponse>` with confirmation result

#### `get(txHash: string)`

Get a transaction by hash.

```typescript
const tx = await sdk.transaction.get('5Kd3N...')

console.log('Transaction:', tx.hash)
console.log('Signer:', tx.tx.signer)
console.log('Action:', tx.tx.action)
console.log('Receipt:', tx.receipt)
```

**Parameters**:

* `txHash` (string): Transaction hash (Base58 encoded)

**Returns**: `Promise<Transaction>` with transaction data

#### `getTransactionsInEntry(entryHash: string)`

Get all transactions in a specific entry.

```typescript
const { txs } = await sdk.transaction.getTransactionsInEntry('5Kd3N...')

txs.forEach((tx) => {
	console.log('Transaction:', tx.hash)
})
```

**Parameters**:

* `entryHash` (string): Entry hash (Base58 encoded)

**Returns**: `Promise<GetTransactionsInEntryResponse>` with transactions

### Contract API

Interact with smart contracts and query contract data.

#### `get(key: Uint8Array | string)`

Get contract data by key.

```typescript
const data = await sdk.contract.get(keyBytes)
// or
const data = await sdk.contract.get('5Kd3N...') // Base58 encoded key

console.log('Contract data:', data)
```

**Parameters**:

* `key` (Uint8Array | string): Contract key as Uint8Array or Base58 string

**Returns**: `Promise<ContractDataValue>` with contract data

#### `getPrefix(key: Uint8Array | string)`

Get contract data by key prefix.

```typescript
const data = await sdk.contract.getPrefix(keyPrefix)

data.forEach((item) => {
	console.log('Key:', item.key)
	console.log('Value:', item.value)
})
```

**Parameters**:

* `key` (Uint8Array | string): Contract key prefix

**Returns**: `Promise<ContractDataValue[]>` with array of key-value pairs

#### `validateBytecode(bytecode: Uint8Array | ArrayBuffer)`

Validate contract bytecode.

```typescript
const result = await sdk.contract.validateBytecode(wasmBytecode)

if (result.error === 'ok') {
	console.log('Bytecode is valid')
} else {
	console.error('Validation error:', result.error)
}
```

**Parameters**:

* `bytecode` (Uint8Array | ArrayBuffer): Contract bytecode to validate

**Returns**: `Promise<ValidateBytecodeResponse>` with validation result

#### `getRichlist()`

Get contract richlist (token holders).

```typescript
const { richlist } = await sdk.contract.getRichlist()

richlist.forEach((entry) => {
	console.log('Address:', entry.address)
	console.log('Balance:', entry.balance)
	console.log('Rank:', entry.rank)
})
```

**Returns**: `Promise<GetRichlistResponse>` with richlist entries

### Epoch API

Query epoch and validator data.

#### `getScore(publicKey?: string)`

Get epoch score(s).

```typescript
// Get score for specific validator
const score = await sdk.epoch.getScore('5Kd3N...')
console.log('Score:', score.score)

// Get all scores
const allScores = await sdk.epoch.getScore()
allScores.forEach(([address, score]) => {
	console.log(`${address}: ${score}`)
})
```

**Parameters**:

* `publicKey` (string, optional): Validator public key (Base58 encoded)

**Returns**: `Promise<EpochScore | EpochScore[]>` with score(s)

#### `getAllScores()`

Get all epoch scores.

```typescript
const scores = await sdk.epoch.getAllScores()

scores.forEach(([address, score]) => {
	console.log(`${address}: ${score}`)
})
```

**Returns**: `Promise<EpochScore[]>` with all scores

#### `getTopValidators(limit: number)`

Get top validators by score.

```typescript
const topValidators = await sdk.epoch.getTopValidators(10)

topValidators.forEach(([address, score]) => {
	console.log(`${address}: ${score}`)
})
```

**Parameters**:

* `limit` (number): Number of top validators to return

**Returns**: `Promise<EpochScore[]>` with top validators

#### `getEmissionAddress()`

Get the current emission address.

```typescript
const { emission_address } = await sdk.epoch.getEmissionAddress()

if (emission_address) {
	console.log('Emission address:', emission_address)
} else {
	console.log('No emission address set')
}
```

**Returns**: `Promise<GetEmissionAddressResponse>` with emission address

#### `getSolInEpoch(epoch: number, solutionHash: string)`

Check if a solution is in a specific epoch.

```typescript
const result = await sdk.epoch.getSolInEpoch(100, '5Kd3N...')

if (result.error === 'ok') {
	console.log('Solution found in epoch')
} else if (result.error === 'sol_not_found') {
	console.log('Solution not found')
} else {
	console.log('Invalid epoch')
}
```

**Parameters**:

* `epoch` (number): Epoch number
* `solutionHash` (string): Solution hash (Base58 encoded)

**Returns**: `Promise<GetSolInEpochResponse>` with check result

### Peer API

Query network peer information.

#### `getNodes()`

Get all network nodes.

```typescript
const nodes = await sdk.peer.getNodes()

nodes.forEach((node) => {
	console.log('Public Key:', node.pk)
	console.log('Version:', node.version)
	console.log('Height:', node.temporal_height)
	console.log('Online:', node.online)
})
```

**Returns**: `Promise<PeerInfo[]>` with node information

#### `getTrainers()`

Get all trainers.

```typescript
const trainers = await sdk.peer.getTrainers()

trainers.forEach((trainer) => {
	console.log('Trainer:', trainer.pk)
	console.log('Is Trainer:', trainer.is_trainer)
})
```

**Returns**: `Promise<PeerInfo[]>` with trainer information

#### `getRemovedTrainers()`

Get removed trainers.

```typescript
const removed = await sdk.peer.getRemovedTrainers()

removed.forEach((trainer) => {
	console.log('Removed trainer:', trainer.pk)
})
```

**Returns**: `Promise<PeerInfo[]>` with removed trainer information

#### `getANRs()`

Get ANR (Autonomous Network Registry) entries.

```typescript
const anrs = await sdk.peer.getANRs()

anrs.forEach((anr) => {
	console.log('Public Key:', anr.pk)
	console.log('IP:', anr.ip4)
	console.log('Port:', anr.port)
	console.log('Version:', anr.version)
})
```

**Returns**: `Promise<ANRInfo[]>` with ANR information

#### `getANRByPk(publicKey: string)`

Get ANR entry by public key.

```typescript
const anr = await sdk.peer.getANRByPk('5Kd3N...')

console.log('ANR:', anr)
```

**Parameters**:

* `publicKey` (string): Public key (Base58 encoded)

**Returns**: `Promise<ANRInfo>` with ANR information

### Proof API

Query validator proofs.

#### `getValidators(entryHash: string)`

Get validator proof for an entry.

```typescript
const proof = await sdk.proof.getValidators('5Kd3N...')

console.log('Key:', proof.key)
console.log('Value:', proof.value)
console.log('Validators:', proof.validators)
console.log('Proof:', proof.proof)
```

**Parameters**:

* `entryHash` (string): Entry hash (Base58 encoded)

**Returns**: `Promise<ProofValidators>` with validator proof

### Error Handling

All API methods throw `AmadeusSDKError` on failure:

```typescript
import { AmadeusSDKError } from '@amadeus-protocol/sdk'

try {
	const balance = await sdk.wallet.getBalance(address, 'AMA')
} catch (error) {
	if (error instanceof AmadeusSDKError) {
		console.error('SDK Error:', error.message)
		console.error('Status:', error.status)
		console.error('Response:', error.response)
	}
}
```

### Next Steps

* [**Utilities**: Learn about utility functions](/sdk/6.-utilities.md)
* [**Examples**: See complete API usage examples](/sdk/7.-examples.md)
* [**Best Practices**: Development guidelines](/sdk/8.-best-practices.md)