> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repstation.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get up and running with IOTA Repstation in 5 minutes

## Installation

Install the IOTA Repstation SDK using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install @repstation/sdk
  ```

  ```bash yarn theme={null}
  yarn add @repstation/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @repstation/sdk
  ```
</CodeGroup>

## Basic Setup

<Steps>
  <Step title="Import the SDK">
    Import the appropriate client for your environment:

    <CodeGroup>
      ```javascript Browser/Frontend theme={null}
      import { RepstationClient } from '@repstation/sdk';
      ```

      ```javascript Server/Backend theme={null}
      import { createServer } from '@repstation/sdk/server';
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize the Client">
    Create a client instance with your configuration:

    <CodeGroup>
      ```javascript Browser theme={null}
      // Optional: create IOTA client for real blockchain interactions
      const iotaClient = new IotaClient({
        url: 'https://api.testnet.iota.cafe'
      });

      const client = new RepstationClient({
        network: 'testnet', // or 'mainnet'
        rpcUrl: 'https://api.testnet.iota.cafe',
        client: iotaClient // Optional
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Register Your Application (Server-side)">
    If you're setting up a new platform, register it first:

    ```javascript theme={null}
      const tx = client.registerApp({
        providerMetadata: {
          providerName: 'Repstation',
          publicUrl: 'https://repstation.xyz',
          xHandle: '@repstation_xyz', // Optional
        },
      });
    ```
  </Step>
</Steps>

## Your First Integration

Let's build a simple reputation check for a marketplace:

### 1. Check User Reputation

Before allowing a transaction, check the user's reputation:

```javascript theme={null}
async function checkUserReputation(walletAddress) {
  const result = await client.getReputationProfile({ 
    walletAddress 
  });
  
  if (result.success && result.profile) {
    const globalRep = result.profile.global?.average || 0;
    const ratingCount = result.profile.global?.count || 0;
    
    console.log(`User reputation: ${globalRep}/100 (${ratingCount} ratings)`);
    
    // Your business logic
    if (globalRep >= 70 && ratingCount >= 5) {
      return { trusted: true, level: 'high' };
    } else if (globalRep >= 50) {
      return { trusted: true, level: 'medium' };
    } else {
      return { trusted: false, level: 'low' };
    }
  }
  
  return { trusted: false, level: 'new' };
}
```

### 2. Create a Deal

When users start a transaction, create a deal:

```javascript theme={null}
async function createDeal(sellerWallet, buyerWallet, itemId, price) {
  const { dealId } = await client.openDeal({
    partyB: buyerWallet,
    subjectRef: { type: 'NFT', id: itemId },
    amount: price.toString()
  });
  
  // Store dealId with your transaction record
  await database.transactions.create({
    itemId,
    seller: sellerWallet,
    buyer: buyerWallet,
    price,
    reputationDealId: dealId,
    status: 'pending'
  });
  
  return dealId;
}
```

### 3. Complete the Deal Flow

Handle the deal lifecycle:

```javascript theme={null}
// When buyer confirms purchase
async function confirmPurchase(transactionId, buyerAddress) {
  const transaction = await database.transactions.findById(transactionId);
  
  // Process payment through your system
  await processPayment(transaction);
  
  // Accept the reputation deal
  await client.acceptDeal({
    dealId: transaction.reputationDealId
  });
  
  // Update transaction status
  await database.transactions.update(transactionId, { 
    status: 'active' 
  });
}

// When item is delivered/transaction completed
async function completeTrade(transactionId) {
  const transaction = await database.transactions.findById(transactionId);
  
  // After delivery confirmation
  await client.closeDeal({
    dealId: transaction.reputationDealId
  });
  
  // Enable rating UI for both parties
  await database.transactions.update(transactionId, { 
    status: 'completed',
    ratingsEnabled: true 
  });
}
```

### 4. Enable Ratings

After deal completion, allow users to rate each other:

```javascript theme={null}
async function submitRating(dealId, score, category) {
  try {
    const { endorsementId } = await client.rate({
      dealId: dealId,
      score: score, // 1-100
      category: category // 'communication', 'speed', 'quality', etc.
    });
    
    console.log(`Rating submitted: ${endorsementId}`);
    return endorsementId;
  } catch (error) {
    console.error('Rating failed:', error);
    throw error;
  }
}
```

## Frontend Integration

Create a simple rating component:

```jsx theme={null}
import React, { useState, useEffect } from 'react';
import { RepstationClient } from '@repstation/sdk';

function UserReputationBadge({ walletAddress }) {
  const [reputation, setReputation] = useState(null);
  
  useEffect(() => {
    const client = new RepstationClient({
      network: 'testnet',
      packageId: process.env.REACT_APP_CONTRACT_ADDRESS
    });
    
    client.getReputationProfile({ walletAddress })
      .then(result => {
        if (result.success) {
          setReputation(result.profile);
        }
      });
  }, [walletAddress]);
  
  if (!reputation) return <div>Loading...</div>;
  
  const globalRep = reputation.global?.average || 0;
  const ratingCount = reputation.global?.count || 0;
  
  return (
    <div className="reputation-badge">
      <div className="global-rep">
        <span className="score">{globalRep}/100</span>
        <span className="count">({ratingCount} ratings)</span>
      </div>
      
      {reputation.appScoped?.map((app, i) => (
        <div key={i}>
          App {i + 1}: {app.stats.average}/100
        </div>
      ))}
    </div>
  );
}
```

## Testing Your Integration

Use the built-in mock client for development:

```javascript theme={null}
// The SDK automatically uses mocks when no real IOTA client is provided
const mockClient = new RepstationClient({
  network: 'testnet',
  packageId: '0xMOCK_PACKAGE'
  // No real client - uses MockIotaClient internally
});

// All operations return mock data
const mockDeal = await mockClient.openDealAdmin({
  party_b: '0xMOCK_ADDRESS',
  subject_ref: { type: 'TEST', id: '123' },
  amount: '1000'
});

console.log(mockDeal.deal_id); // Returns mock object ID
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book" href="/concepts/overview">
    Understand deals, ratings, and reputation in depth.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the complete SDK API documentation.
  </Card>

  <Card title="Integration Examples" icon="puzzle-piece" href="/integration/marketplace-example">
    See detailed examples for different platform types.
  </Card>

  <Card title="Error Handling" icon="shield-check" href="/api-reference/client#error-handling">
    Learn about error handling and best practices.
  </Card>
</CardGroup>

<Tip>
  Start with the testnet for development and testing. When you're ready for production, simply change the `network` parameter to `'mainnet'`.
</Tip>

<Warning>
  Always store deal IDs with your transaction records. You'll need them for completing the deal lifecycle and enabling ratings.
</Warning>