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


---

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