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:
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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).
// 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.
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.
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.
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.
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 numbersolutionHash(string): Solution hash (Base58 encoded)
Returns: Promise<GetSolInEpochResponse> with check result
Peer API
Query network peer information.
getNodes()
Get all network nodes.
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.
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.
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.
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.
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.
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:
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)
}
}