CrossEra SDK

Official SDK for CrossEra - CrossFi Reward System. This SDK provides easy access to CrossEra's reward system functionality with efficient batch processing as the primary method for transaction submission.

Installation

npm install @crossera/sdk

Quick Start

import { CrossEraSDK } from '@crossera/sdk';

const sdk = new CrossEraSDK();

// Get app ID by address
const appId = await sdk.getAppIdByAddress({
  address: '0x46992B61b7A1d2e4F59Cd881B74A96a549EF49BF',
  network: 'testnet'
});

// Submit transaction for batch processing (recommended)
const result = await sdk.submitForProcessing({
  transactionHash: '0x753b2ea96cdf8dd1b5a822f4f40ea0678c3516b44946a78ae26863dc1425d468',
  network: 'mainnet'
});

console.log('Queued for processing:', result);
// {
//   success: true,
//   status: 'pending',
//   estimatedProcessingTime: '~14 hours (next batch runs at 00:00 UTC)'
// }

// Check status later
const status = await sdk.getTransactionStatus({
  transactionHash: '0x753b2ea96cdf8dd1b5a822f4f40ea0678c3516b44946a78ae26863dc1425d468',
  network: 'mainnet'
});

API Reference

CrossEraSDK

Constructor

new CrossEraSDK(config?: SDKConfig)

Parameters:

• config (optional): SDK configuration object
  • defaultNetwork?: Network - Default network to use
  • timeout?: number - Request timeout in milliseconds
  • apiKey?: string - API key for authentication (future use)

Methods

getAppIdByAddress

Get app ID by wallet address on specified network.

async getAppIdByAddress(params: GetAppIdParams): Promise<string | null>

Parameters:

• params.address - Wallet address (0x format)
• params.network - Network to query ('testnet' or 'mainnet')

Returns: App ID string or null if not found

Example:

const appId = await sdk.getAppIdByAddress({
  address: '0x46992B61b7A1d2e4F59Cd881B74A96a549EF49BF',
  network: 'testnet'
});

submitForProcessing (Primary Method)

Submit transaction for batch processing (processed daily at 00:00 UTC). This is the recommended method for most use cases.

async submitForProcessing(params: SubmitForProcessingParams): Promise<BatchTransactionResult>

Parameters:

• params.transactionHash - Transaction hash (0x format)
• params.network - Network to submit to ('testnet' or 'mainnet')
• params.appId - (Optional) App ID - will be extracted from transaction if not provided
• params.userAddress - (Optional) User address - will be extracted from transaction if not provided

Returns: Batch transaction result with pending status

Example:

const sdk = new CrossEraSDK();

// Submit for batch processing
const result = await sdk.submitForProcessing({
  transactionHash: '0x753b2ea96cdf8dd1b5a822f4f40ea0678c3516b44946a78ae26863dc1425d468',
  network: 'mainnet',
  appId: 'my-app-id',        // Optional
  userAddress: '0x...'       // Optional
});

console.log('Submitted!');
console.log('Status:', result.status);                    // 'pending'
console.log('Estimated time:', result.estimatedProcessingTime); // '~14 hours'
console.log('ID:', result.id);                           // UUID for tracking

Response:

{
  success: true,
  transactionHash: '0x...',
  appId: 'my-app-id',
  userAddress: '0x...',
  network: 'mainnet',
  status: 'pending',
  submittedAt: '2025-10-06T10:30:00Z',
  estimatedProcessingTime: '~14 hours (next batch runs at 00:00 UTC)',
  id: '76d2d5b4-85c2-4ca0-8a9c-cc4f8190baac'
}

Usage Examples

React Hook

import { CrossEraSDK, Network } from '@crossera/sdk';
import { useCallback, useMemo } from 'react';

function useCrossEra(network: Network) {
  const sdk = useMemo(() => new CrossEraSDK(), []);
  
  const getAppId = useCallback(async (address: string) => {
    try {
      return await sdk.getAppIdByAddress({ address, network });
    } catch (error) {
      console.error(`Failed to get app ID on ${network}:`, error);
      return null;
    }
  }, [sdk, network]);
  
  const submitTransaction = useCallback(async (hash: string) => {
    try {
      return await sdk.submitForProcessing({ transactionHash: hash, network });
    } catch (error) {
      console.error(`Failed to submit transaction on ${network}:`, error);
      throw error;
    }
  }, [sdk, network]);
  
  return { getAppId, submitTransaction };
}

Error Handling

import { CrossEraSDK } from '@crossera/sdk';

const sdk = new CrossEraSDK();

async function handleAppIdLookup(address: string, network: Network) {
  try {
    const appId = await sdk.getAppIdByAddress({ address, network });
    
    if (appId) {
      console.log(`App ID found on ${network}:`, appId);
    } else {
      console.log(`No app ID found for address ${address} on ${network}`);
    }
    
    return appId;
  } catch (error) {
    console.error(`Error looking up app ID on ${network}:`, error.message);
    throw error;
  }
}

Error Handling

The SDK provides comprehensive error handling:

• Validation Errors: Invalid address, transaction hash, or network
• Network Errors: Connection issues or server errors
• API Errors: Specific error messages from the API

All errors include context about the network and operation that failed.

License

MIT

Support

For support and questions:

• GitHub Issues: https://github.com/crossera/crossera-sdk/issues
• Documentation: https://crossera.vercel.app