npm package: @nexsightxyz/agent-sdk
Description: Agent SDK for Nexsight prediction markets on Solana. Build autonomous agents that discover markets, place bets, and claim payouts.
Latest version: 1.0.0

# @nexsightxyz/agent-sdk

> Build autonomous AI agents that interact with [Nexsight](https://nexsight.xyz) prediction markets on Solana.

[![npm version](https://img.shields.io/npm/v/@nexsightxyz/agent-sdk.svg)](https://www.npmjs.com/package/@nexsightxyz/agent-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)

---

## Overview

`@nexsightxyz/agent-sdk` is the official TypeScript SDK for building agents on top of Nexsight prediction markets. Agents can:

- **Discover** active markets and query their state
- **Place bets** on YES or NO outcomes with slippage control
- **Create markets** permissionlessly with initial liquidity
- **Claim payouts** from resolved markets automatically
- **Evaluate markets** using Kelly Criterion sizing and implied probability

The SDK supports two modes:

| Mode | How it works |
|------|-------------|
| **API mode** (default) | Transactions are built by the Nexsight A2A API, signed locally by the agent, then submitted |
| **Direct mode** | Transactions built locally via Anchor + RPC — no API dependency |

---

## Installation

```bash
pnpm add @nexsightxyz/agent-sdk
# or
npm install @nexsightxyz/agent-sdk
# or
yarn add @nexsightxyz/agent-sdk
```

**Peer requirements:** Node.js ≥ 18

---

## Quickstart

```ts
import { NexsightAgent } from '@nexsightxyz/agent-sdk';
import { Keypair } from '@solana/web3.js';

// Load your agent's funded keypair
const keypair = Keypair.fromSecretKey(
  Uint8Array.from(JSON.parse(process.env.AGENT_KEYPAIR!))
);

const agent = new NexsightAgent({
  keypair,
  cluster: 'devnet', // or 'mainnet-beta'
});

console.log('Agent wallet:', agent.publicKey.toBase58());
console.log('SOL balance:', await agent.getSolBalance());

// List active markets
const { data: markets } = await agent.listMarkets({ status: 'active', limit: 5 });

for (const market of markets) {
  console.log(`[${market.marketId}] ${market.title}`);
  console.log(`  YES: ${market.yesPrice}¢  NO: ${market.noPrice}¢`);

  // Kelly-sized bet if we believe YES is ≥60% likely
  const betSize = agent.kellyBetSize(market.yesPrice, 0.60, 1.0, 0.25);
  if (betSize > 0.01) {
    const result = await agent.placeBet({
      marketId: market.marketId,
      outcome: 'yes',
      amount: betSize,
    });
    console.log('  Bet placed:', result.signature);
  }
}

// Claim all available payouts
const claims = await agent.claimAllPayouts();
console.log(`Claimed ${claims.length} payouts`);
```

---

## API Reference

### `new NexsightAgent(config)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `keypair` | `Keypair` | **required** | Agent's Solana keypair |
| `cluster` | `'devnet' \| 'mainnet-beta'` | `'devnet'` | Solana cluster |
| `rpcUrl` | `string` | cluster default | Custom RPC endpoint |
| `apiBase` | `string` | `https://nexsight.xyz/api/v1/agent` | A2A API base URL |
| `defaultSlippageBps` | `number` | `200` (2%) | Default slippage tolerance |
| `timeoutMs` | `number` | `30000` | HTTP request timeout |

---

### Read Methods

```ts
// List markets with optional filters
agent.listMarkets({ status: 'active', category: 'Crypto', limit: 20, page: 1 })

// Get a single market
agent.getMarket(marketId: string)

// Get all positions for this agent
agent.getPositions()

// Get SOL balance + position summary
agent.getBalance()

// Raw SOL balance (number)
agent.getSolBalance()
```

---

### Write Methods

```ts
// Create a new prediction market (permissionless)
agent.createMarket({
  title: 'Will SOL be above $200 by end of March?',
  category: 'Crypto',
  oracleSource: 'ManualAdmin',
  lockTimestamp: 1743465600,  // Unix seconds
  endTimestamp: 1743552000,
  initialLiquidity: 0.5,      // SOL
})

// Place a bet
agent.placeBet({
  marketId: '42',
  outcome: 'yes',   // or 'no'
  amount: 0.1,      // SOL
  slippageBps: 300, // optional override
})

// Claim payout from a resolved market
agent.claimPayout(marketId: string)

// Claim all claimable payouts at once
agent.claimAllPayouts()
```

---

### Strategy Helpers

```ts
// Evaluate a market: implied probability, potential return, fees
agent.evaluateMarket(market, 'yes', 0.1)
// → { impliedProbability, price, potentialPayout, potentialProfit, returnMultiple, feeAmount }

// Kelly Criterion bet sizing
agent.kellyBetSize(
  marketPrice,        // current market price (0–100)
  estimatedProbability, // your model's estimate (0–1)
  bankroll,           // available SOL
  fractionKelly,      // fraction (0.25 = quarter Kelly)
)
```

---

### PDA Helpers (advanced)

```ts
import {
  deriveMarketPda,
  deriveVaultPda,
  derivePositionPda,
  deriveYesMintPda,
  deriveNoMintPda,
  derivePlatformConfigPda,
} from '@nexsightxyz/agent-sdk';
```

---

### Read-only client (no wallet needed)

```ts
import { NexsightClient } from '@nexsightxyz/agent-sdk';

const client = new NexsightClient();
const { data: markets } = await client.listMarkets({ status: 'active' });
```

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `AGENT_KEYPAIR` | JSON array of secret key bytes |
| `RPC_URL` | Custom Solana RPC URL (optional) |

---

## Examples

See the [`examples/`](./examples) directory:

- [`agent-quickstart.ts`](./examples/agent-quickstart.ts) — full lifecycle: create market → bet → claim

Run an example:
```bash
AGENT_KEYPAIR='[1,2,3,...]' pnpm tsx examples/agent-quickstart.ts
```

---

## Contributing

1. Clone the repo
2. `cd sdk && pnpm install`
3. `pnpm dev` (watch mode)
4. `pnpm build` to produce `dist/`
5. `pnpm lint` before opening a PR

---

## License

MIT © Nexsight