> 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/2.-getting-started.md).

# 2. Getting Started

This guide will help you get started with the Amadeus Protocol SDK in your project. We'll cover installation, basic setup, and your first queries and transactions.

### Installation

#### Package Installation

Install the SDK using your preferred package manager:

```bash
# npm
npm install @amadeus-protocol/sdk

# yarn
yarn add @amadeus-protocol/sdk

# pnpm
pnpm add @amadeus-protocol/sdk

# bun
bun add @amadeus-protocol/sdk
```

#### Verify Installation

After installation, verify the package is installed correctly:

```bash
# Check package version
npm list @amadeus-protocol/sdk

# Or check in your code
import { AmadeusSDK } from '@amadeus-protocol/sdk'
console.log('SDK Version:', AmadeusSDK.getVersion())
```

### Requirements

#### Node.js

The SDK requires **Node.js version 20.0.0 or higher**.

Check your Node.js version:

```bash
node --version
```

If you need to update Node.js, visit [nodejs.org](https://nodejs.org/).

#### TypeScript (Optional)

TypeScript is optional but highly recommended. The SDK includes complete type definitions.

Install TypeScript:

```bash
npm install -D typescript @types/node
```

#### Browser Support

The SDK works in modern browsers that support:

* **ES2020** features
* **fetch API** (or polyfill)
* **Web Crypto API** (for encryption features)

### Basic Setup

#### Import the SDK

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

#### Initialize the SDK

```typescript
// Using default node URL
const sdk = new AmadeusSDK()

// Or specify a custom node URL
const sdk = new AmadeusSDK({
	baseUrl: 'https://nodes.amadeus.bot/api',
	timeout: 30000 // Optional: request timeout in milliseconds
})
```

### Your First Query

Let's start with a simple chain query:

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

const sdk = new AmadeusSDK()

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

### Your First Transaction

Here's how to build and submit a simple token transfer:

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

const sdk = new AmadeusSDK()

// Generate a keypair (or use an existing one)
const keypair = generateKeypair()
console.log('Public Key (Address):', keypair.publicKey)
console.log('Private Key (Seed):', keypair.privateKey) // Keep this secret!

// Create a transaction builder
const builder = new TransactionBuilder(keypair.privateKey)

// Build and sign a transfer transaction
const { txHash, txPacked } = builder.transfer({
	recipient: '5Kd3N...', // Recipient's address
	amount: 10.5, // Amount in AMA
	symbol: 'AMA' // Token symbol
})

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

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

### TypeScript Configuration

If using TypeScript, ensure your `tsconfig.json` includes:

```json
{
	"compilerOptions": {
		"target": "ES2020",
		"module": "ESNext",
		"lib": ["ES2020"],
		"moduleResolution": "node",
		"esModuleInterop": true,
		"strict": true
	}
}
```

### Common Imports

Here are the most commonly used imports:

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

// Transaction building
import { TransactionBuilder } from '@amadeus-protocol/sdk'

// Key generation
import { generateKeypair, derivePublicKeyFromSeedBase58 } from '@amadeus-protocol/sdk'

// Encoding utilities
import { toBase58, fromBase58 } from '@amadeus-protocol/sdk'

// Amount conversions
import { toAtomicAma, fromAtomicAma } from '@amadeus-protocol/sdk'

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

### Troubleshooting Installation

#### "Module not found" Error

**Problem**: Cannot find module '@amadeus-protocol/sdk'

**Solutions**:

1. Ensure the package is installed:

   ```bash
   npm install @amadeus-protocol/sdk
   ```
2. Check your `package.json`:

   ```json
   {
   	"dependencies": {
   		"@amadeus-protocol/sdk": "^1.0.0"
   	}
   }
   ```
3. Clear cache and reinstall:

   ```bash
   npm cache clean --force
   rm -rf node_modules package-lock.json
   npm install
   ```

#### TypeScript Errors

**Problem**: Type errors when importing

**Solutions**:

1. Ensure TypeScript is installed:

   ```bash
   npm install -D typescript
   ```
2. Check `tsconfig.json`:

   ```json
   {
   	"compilerOptions": {
   		"moduleResolution": "node",
   		"esModuleInterop": true
   	}
   }
   ```
3. Restart your TypeScript server/IDE

#### Node.js Version Issues

**Problem**: Errors related to Node.js version

**Solutions**:

1. Check Node.js version:

   ```bash
   node --version
   ```
2. Update to Node.js 20+ if needed
3. Use a version manager like `nvm`:

   ```bash
   nvm install 20
   nvm use 20
   ```

### Next Steps

Now that you have the SDK installed and running:

1. [**Learn Core Concepts**: Understand keypairs, addresses, and transactions](/sdk/3.-core-concepts.md)
2. [**Build Transactions**: Learn how to create and sign transactions](/sdk/4.-transaction-building.md)
3. [**Explore API Modules**: Discover all available API endpoints](/sdk/5.-api-modules.md)
4. [**Check Examples**: See real-world usage examples](/sdk/7.-examples.md)