> 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/7.-examples.md).

# 7. Examples

Real-world usage examples for the Amadeus Protocol SDK.

### Basic SDK Usage

#### Initialize SDK and Query Chain

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

const sdk = new AmadeusSDK({
	baseUrl: 'https://nodes.amadeus.bot/api'
})

// Get chain tip
const tip = await sdk.chain.getTip()
console.log('Current height:', tip.entry.height)
console.log('Chain hash:', tip.entry.hash)

// Get chain statistics
const stats = await sdk.chain.getStats()
console.log('Total entries:', stats.stats.total_entries)
console.log('Total transactions:', stats.stats.total_transactions)
```

### Key Generation

#### Generate and Use Keypair

```typescript
import { generateKeypair, derivePublicKeyFromSeedBase58 } from '@amadeus-protocol/sdk'

// Generate new keypair
const keypair = generateKeypair()
console.log('Public Key (Address):', keypair.publicKey)
console.log('Private Key (Seed):', keypair.privateKey) // Keep secret!

// Derive public key from existing seed
const publicKey = derivePublicKeyFromSeedBase58(keypair.privateKey)
console.log('Derived Public Key:', publicKey)
```

### Wallet Operations

#### Check Balance

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

const sdk = new AmadeusSDK()
const address = '5Kd3N...'

// Get specific token balance
const balance = await sdk.wallet.getBalance(address, 'AMA')
console.log('AMA Balance:', balance.balance.float)

// Get all token balances
const allBalances = await sdk.wallet.getAllBalances(address)
Object.entries(allBalances.balances).forEach(([symbol, balance]) => {
	console.log(`${symbol}: ${balance.float}`)
})
```

#### Get Transaction History

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

const sdk = new AmadeusSDK()
const address = '5Kd3N...'

// Get recent transactions
const { txs, cursor } = await sdk.wallet.getTransactions(address, {
	limit: 10,
	sort: 'desc'
})

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

### Transaction Building

#### Simple Token Transfer

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

const sdk = new AmadeusSDK()

// Generate or use existing keypair
const keypair = generateKeypair()
const builder = new TransactionBuilder(keypair.privateKey)

// Build and sign transfer
const { txHash, txPacked } = builder.transfer({
	recipient: '5Kd3N...',
	amount: 10.5,
	symbol: 'AMA'
})

console.log('Transaction hash:', txHash)

// Submit transaction
const result = await sdk.transaction.submit(txPacked)
if (result.error === 'ok') {
	console.log('Transaction submitted:', result.hash)
} else {
	console.error('Error:', result.error)
}
```

#### Transfer with Confirmation

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

const sdk = new AmadeusSDK()
const keypair = generateKeypair()
const builder = new TransactionBuilder(keypair.privateKey)

// Build and sign
const { txHash, txPacked } = builder.transfer({
	recipient: '5Kd3N...',
	amount: 10.5,
	symbol: 'AMA'
})

// Submit and wait for confirmation
try {
	const result = await sdk.transaction.submitAndWait(txPacked)

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

#### Custom Contract Call

```typescript
import { AmadeusSDK, TransactionBuilder, fromBase58, toAtomicAma } from '@amadeus-protocol/sdk'

const sdk = new AmadeusSDK()
const builder = new TransactionBuilder(privateKey)

// Build custom contract call
const { txHash, txPacked } = builder.buildAndSign('MyContract', 'myMethod', [
	fromBase58('5Kd3N...'),
	toAtomicAma(100).toString(),
	'AMA',
	'additional-arg'
])

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

#### Build Unsigned, Inspect, Then Sign

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

const builder = new TransactionBuilder(privateKey)

// Build unsigned transaction
const unsignedTx = builder.buildTransfer({
	recipient: '5Kd3N...',
	amount: 10.5,
	symbol: 'AMA'
})

// Inspect transaction
console.log('Nonce:', unsignedTx.tx.nonce.toString())
console.log('Signer:', unsignedTx.tx.signer)
console.log('Action:', unsignedTx.tx.action)
console.log('Hash:', unsignedTx.hash)

// Sign the transaction
const { txHash, txPacked } = builder.sign(unsignedTx)
```

### Contract Interactions

#### Read Contract Data

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

const sdk = new AmadeusSDK()

// Get contract data by key
const key = fromBase58('5Kd3N...')
const data = await sdk.contract.get(key)
console.log('Contract data:', data)

// Get contract data by prefix
const prefixData = await sdk.contract.getPrefix(key)
prefixData.forEach((item) => {
	console.log('Key:', item.key)
	console.log('Value:', item.value)
})
```

#### Validate Bytecode

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

const sdk = new AmadeusSDK()

// Load WASM bytecode
const wasmBytecode = await fetch('contract.wasm').then((r) => r.arrayBuffer())

// Validate bytecode
const result = await sdk.contract.validateBytecode(wasmBytecode)
if (result.error === 'ok') {
	console.log('Bytecode is valid')
} else {
	console.error('Validation error:', result.error)
}
```

#### Get Richlist

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

const sdk = new AmadeusSDK()

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

richlist.slice(0, 10).forEach((entry) => {
	console.log(`Rank ${entry.rank}: ${entry.address} - ${entry.balance} ${entry.symbol}`)
})
```

### Encryption

#### Encrypt and Store Private Key

```typescript
import { encryptWithPassword, decryptWithPassword, generateKeypair } from '@amadeus-protocol/sdk'

// Generate keypair
const keypair = generateKeypair()

// Encrypt private key with user password
const encrypted = await encryptWithPassword(keypair.privateKey, 'user-password-123')

// Store encrypted data (in real app, use secure storage)
const storage = {
	encryptedData: encrypted.encryptedData,
	iv: encrypted.iv,
	salt: encrypted.salt
}

// Later: Decrypt when user enters password
const decryptedKey = await decryptWithPassword(
	{
		encryptedData: storage.encryptedData,
		iv: storage.iv,
		salt: storage.salt
	},
	'user-password-123'
)

console.log('Decrypted key matches:', decryptedKey === keypair.privateKey)
```

### Error Handling

#### Comprehensive Error Handling

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

const sdk = new AmadeusSDK()

async function safeGetBalance(address: string, symbol: string) {
	try {
		const balance = await sdk.wallet.getBalance(address, symbol)
		return balance
	} catch (error) {
		if (error instanceof AmadeusSDKError) {
			if (error.status === 404) {
				console.log('Address not found or has no balance')
				return null
			} else if (error.status === 400) {
				console.error('Invalid address format')
				throw new Error('Invalid address')
			} else {
				console.error('SDK Error:', error.message)
				throw error
			}
		} else {
			console.error('Unexpected error:', error)
			throw error
		}
	}
}
```

### Complete Transaction Flow

#### End-to-End Transaction Example

```typescript
import { AmadeusSDK, TransactionBuilder, generateKeypair, toAtomicAma } from '@amadeus-protocol/sdk'

async function completeTransferFlow() {
	// Initialize SDK
	const sdk = new AmadeusSDK({
		baseUrl: 'https://nodes.amadeus.bot/api'
	})

	// Generate or load keypair
	const keypair = generateKeypair()
	const senderAddress = keypair.publicKey
	const recipientAddress = '5Kd3N...' // Recipient's address

	// Check sender balance
	const balance = await sdk.wallet.getBalance(senderAddress, 'AMA')
	const amount = 10.5
	const transferAmount = toAtomicAma(amount)

	if (balance.balance.flat < transferAmount) {
		throw new Error('Insufficient balance')
	}

	console.log(`Balance: ${balance.balance.float} AMA`)
	console.log(`Transferring: ${amount} AMA`)

	// Build and sign transaction
	const builder = new TransactionBuilder(keypair.privateKey)
	const { txHash, txPacked } = builder.transfer({
		recipient: recipientAddress,
		amount: amount,
		symbol: 'AMA'
	})

	console.log('Transaction hash:', txHash)

	// Submit transaction
	const submitResult = await sdk.transaction.submit(txPacked)

	if (submitResult.error !== 'ok') {
		throw new Error(`Transaction error: ${submitResult.error}`)
	}

	console.log('Transaction submitted:', submitResult.hash)

	// Wait for confirmation
	try {
		const confirmResult = await sdk.transaction.submitAndWait(txPacked)

		if (confirmResult.error === 'ok') {
			console.log('Transaction confirmed!')
			console.log('Entry hash:', confirmResult.metadata?.entry_hash)
			console.log('Receipt:', confirmResult.receipt)
		}
	} catch (error) {
		console.error('Confirmation timeout:', error)
	}

	// Verify transaction
	const tx = await sdk.transaction.get(txHash)
	console.log('Verified transaction:', tx.hash)
}

// Run the flow
completeTransferFlow().catch(console.error)
```

### Batch Operations

#### Submit Multiple Transactions

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

const sdk = new AmadeusSDK()
const builder = new TransactionBuilder(privateKey)

async function submitBatch(transfers: Array<{ recipient: string; amount: number }>) {
	const results = []

	for (const transfer of transfers) {
		try {
			// Build and sign
			const { txHash, txPacked } = builder.transfer({
				recipient: transfer.recipient,
				amount: transfer.amount,
				symbol: 'AMA'
			})

			// Submit
			const result = await sdk.transaction.submit(txPacked)

			results.push({
				recipient: transfer.recipient,
				hash: result.hash,
				error: result.error
			})

			// Small delay to avoid nonce collisions
			await new Promise((resolve) => setTimeout(resolve, 100))
		} catch (error) {
			results.push({
				recipient: transfer.recipient,
				error: error.message
			})
		}
	}

	return results
}
```

### Next Steps

* [**Best Practices**: Learn security and development guidelines](/sdk/8.-best-practices.md)
* [**Troubleshooting**: Common issues and solutions](/sdk/9.-troubleshooting.md)
* [**API Modules**: Complete API reference](/sdk/5.-api-modules.md)