# 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)


---

# Agent Instructions: 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.ama.one/sdk/7.-examples.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.