whales-otc-pre-market-aptos-sdk/README.md

TypeScript SDK for Whales OTC Pre-Market trading on Aptos blockchain

# Whales OTC Pre-Market Aptos SDK

A TypeScript SDK for interacting with Whales OTC (Over-The-Counter) Pre-Market trading contracts on the Aptos blockchain.

## Installation

```bash
npm install whales-otc-pre-market-aptos-sdk
```

## Quick Start

```typescript
import { OTCPreMarketAptos, Network } from "whales-otc-pre-market-aptos-sdk";

// Initialize the SDK
const sdk = new OTCPreMarketAptos({
  network: Network.TESTNET, // or Network.MAINNET
});

// Get configuration
const config = await sdk.getConfig();
console.log(config);

// Get an OTC offer
const offer = await sdk.getOtcOffer("0x...offer_address");
console.log(offer);
```

## Features

- **OTC Trading**: Create, fill, update, and cancel OTC offers
- **Batch Operations**: Support for batch creation and cancellation of offers
- **Role Management**: Admin functions for role-based access control
- **Event Crawling**: Built-in event crawler for monitoring blockchain events
- **GraphQL Support**: Optional GraphQL integration for enhanced data querying
- **Type Safety**: Full TypeScript support with comprehensive type definitions

## Configuration

### Basic Configuration

```typescript
import { OTCPreMarketAptos, Network } from "whales-otc-pre-market-aptos-sdk";

const sdk = new OTCPreMarketAptos({
  network: Network.MAINNET,
  // Additional Aptos configuration options...
});
```

### With GraphQL Support

```typescript
import { OTCPreMarketAptos, Network } from "whales-otc-pre-market-aptos-sdk";

const sdk = new OTCPreMarketAptos(
  {
    network: Network.MAINNET,
  },
  {
    endpoint: "https://your-graphql-endpoint.com/graphql",
    // Additional GraphQL configuration...
  }
);
```

## Core Methods

### Reading Data

```typescript
// Get platform configuration
const config = await sdk.getConfig();

// Get OTC offer details
const offer = await sdk.getOtcOffer("0x...offer_address");

// Get user role
const role = await sdk.getRole("0x...user_address");

// Check if offer is expired
const isExpired = await sdk.isOfferExpired("0x...offer_address");
```

### Creating Offers

```typescript
// Create a single offer
const { rawTx, txData } = await sdk.buildCreateOffer("0x...user_address", {
  orderObj: "0x...order_address",
  isBuyer: true,
  exToken: "0x...token_address",
  value: 1000000, // Amount in token's smallest unit
  deadline: Date.now() + 86400000, // 24 hours from now
});

// Batch create multiple offers
const { rawTx: batchTx, txData: batchTxData } = await sdk.buildBatchCreateOffer(
  "0x...user_address",
  {
    orderObjs: ["0x...order1", "0x...order2"],
    isBuyers: [true, false],
    exTokens: ["0x...token1", "0x...token2"],
    values: [1000000, 2000000],
    deadlines: [deadline1, deadline2],
  }
);
```

### Managing Offers

```typescript
// Fill an offer
const { rawTx, txData } = await sdk.buildFillOffer(
  "0x...user_address",
  "0x...offer_address"
);

// Update an offer
const { rawTx, txData } = await sdk.buildUpdateOffer("0x...user_address", {
  offerObj: "0x...offer_address",
  newValue: 1500000,
  newDeadline: Date.now() + 172800000, // 48 hours from now
});

// Cancel an offer
const { rawTx, txData } = await sdk.buildCancelOffer(
  "0x...user_address",
  "0x...offer_address"
);

// Cancel expired offers (batch)
const { rawTx, txData } = await sdk.buildCancelExpiredOffers(
  "0x...user_address",
  ["0x...offer1", "0x...offer2"]
);
```

### Administrative Functions

```typescript
// Add role to user (requires admin privileges)
const { rawTx, txData } = await sdk.buildAddRole(
  "0x...admin_address",
  "0x...user_address",
  Role.OPERATOR
);

// Remove role from user
const { rawTx, txData } = await sdk.buildRemoveRole(
  "0x...admin_address",
  "0x...user_address"
);

// Update platform configuration
const { rawTx, txData } = await sdk.buildUpdateConfig("0x...owner_address", {
  feePercent: 100, // 1% (basis points)
  feeWallet: "0x...new_fee_wallet",
});

// Force cancel offers (operator function)
const { rawTx, txData } = await sdk.buildForceCancelOffers(
  "0x...operator_address",
  ["0x...offer1", "0x...offer2"]
);
```

## Event Crawling

The SDK includes a built-in event crawler for monitoring blockchain events:

```typescript
const lastTxVersion = 0;
const limit = 100;

// Access the event crawler
const events = await sdk.eventCrawler.getEventsV2(lastTxVersion, limit);

console.log(events);
```

## Types and Enums

The SDK exports comprehensive TypeScript types:

```typescript
import {
  ConfigData,
  OtcOfferData,
  Role,
  OTCPreMarketError,
  TokenStatus,
  OfferType,
} from "whales-otc-pre-market-aptos-sdk";
```

## Network Support

The SDK supports both Aptos Mainnet and Testnet:

```typescript
import { Network } from "@aptos-labs/ts-sdk";

// Testnet
const testnetSdk = new OTCPreMarketAptos({ network: Network.TESTNET });

// Mainnet
const mainnetSdk = new OTCPreMarketAptos({ network: Network.MAINNET });
```

## Requirements

- Node.js >= 22.0.0
- TypeScript >= 5.8.3

## License

MIT

## Contributing

Please read our contributing guidelines before submitting pull requests.

## Support

For support and questions, please open an issue on GitHub or contact the Whales team.