Quickstart Guide

Installation

Install the IOTA Repstation SDK using your preferred package manager:

npm install @repstation/sdk

yarn add @repstation/sdk

pnpm add @repstation/sdk

Basic Setup

Import the SDK

Import the appropriate client for your environment:

import { RepstationClient } from '@repstation/sdk';

import { createServer } from '@repstation/sdk/server';

Initialize the Client

Create a client instance with your configuration:

// 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
});

If you’re setting up a new platform, register it first:

  const tx = client.registerApp({
    providerMetadata: {
      providerName: 'Repstation',
      publicUrl: 'https://repstation.xyz',
      xHandle: '@repstation_xyz', // Optional
    },
  });

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:

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:

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:

// 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:

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:

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:

// 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

Core Concepts

Understand deals, ratings, and reputation in depth.

API Reference

Explore the complete SDK API documentation.

Integration Examples

See detailed examples for different platform types.

Error Handling

Learn about error handling and best practices.

Start with the testnet for development and testing. When you’re ready for production, simply change the network parameter to 'mainnet'.

Always store deal IDs with your transaction records. You’ll need them for completing the deal lifecycle and enabling ratings.

Getting Started

Core Concepts

Integration Guide

Examples

Installation

Basic Setup

Your First Integration

1. Check User Reputation

2. Create a Deal

3. Complete the Deal Flow

4. Enable Ratings

Frontend Integration

Testing Your Integration

Next Steps

Core Concepts

API Reference

Integration Examples

Error Handling

​Installation

​Basic Setup

​Your First Integration

​1. Check User Reputation

​2. Create a Deal

​3. Complete the Deal Flow

​4. Enable Ratings

​Frontend Integration

​Testing Your Integration

​Next Steps

Core Concepts

API Reference

Integration Examples

Error Handling

Installation

Basic Setup

Your First Integration

1. Check User Reputation

2. Create a Deal

3. Complete the Deal Flow

4. Enable Ratings

Frontend Integration

Testing Your Integration

Next Steps