--- name: poseidon-otc description: Execute trustless P2P token swaps on Solana via the Poseidon OTC protocol. Create trade rooms, negotiate offers, lock tokens with time-based escrow, and execute atomic on-chain swaps. Supports agent-to-agent trading with real-time WebSocket updates. metadata: { "openclaw": { "emoji": "🔱", "requires": { "env": ["POSEIDON_BURNER_KEY"] }, "primaryEnv": "POSEIDON_BURNER_KEY", "homepage": "https://poseidon.cash" } } ---

Poseidon OTC Skill

TL;DR for Agents: This skill lets you trade tokens with humans or other agents on Solana. You create a room, both parties deposit tokens to escrow, confirm, and execute an atomic swap. No trust required - it's all on-chain.

When to Use This Skill

• Trading tokens P2P - Swap any SPL token directly with another party
• Agent-to-agent commerce - Two AI agents can negotiate and execute trades autonomously
• Large OTC deals - Avoid slippage from DEX trades by going direct
• Protected trades - Use lockups to prevent counterparty from dumping immediately
• Multi-token swaps - Trade up to 4 tokens per side in one atomic transaction

Quick Start for Agents

1. Initialize (requires wallet)

import { PoseidonOTC } from 'poseidon-otc-skill';

const client = new PoseidonOTC({
  burnerKey: process.env.POSEIDON_BURNER_KEY  // base58 private key
});

2. Create a Trade Room

const { roomId, link } = await client.createRoom();
// Share `link` with counterparty or another agent

3. Wait for Counterparty & Set Offer

// Check room status
const room = await client.getRoom(roomId);

// Set what you're offering (100 USDC example)
await client.updateOffer(roomId, [{
  mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',  // USDC mint
  amount: 100000000,  // 100 USDC (6 decimals)
  decimals: 6
}]);

4. Confirm & Execute

// First confirmation = "I agree to these terms"
await client.confirmTrade(roomId, 'first');

// After deposits, second confirmation
await client.confirmTrade(roomId, 'second');

// Execute the atomic swap
const { txSignature } = await client.executeSwap(roomId);

Complete Trade Flow

┌─────────────────────────────────────────────────────────────────┐
│                        TRADE LIFECYCLE                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. CREATE ROOM                                                 │
│     └─> Party A calls createRoom()                              │
│         Returns: roomId, shareable link                         │
│                                                                 │
│  2. JOIN ROOM                                                   │
│     └─> Party B calls joinRoom(roomId)                          │
│         Room now has both participants                          │
│                                                                 │
│  3. SET OFFERS                                                  │
│     └─> Both parties call updateOffer(roomId, tokens)           │
│         Each specifies what they're putting up                  │
│                                                                 │
│  4. FIRST CONFIRM (agree on terms)                              │
│     └─> Both call confirmTrade(roomId, 'first')                 │
│         "I agree to swap my X for your Y"                       │
│                                                                 │
│  5. DEPOSIT TO ESCROW                                           │
│     └─> Tokens move to on-chain escrow                          │
│         (Handled by frontend or depositToEscrow)                │
│                                                                 │
│  6. SECOND CONFIRM (verify deposits)                            │
│     └─> Both call confirmTrade(roomId, 'second')                │
│         "I see the deposits, ready to swap"                     │
│                                                                 │
│  7. EXECUTE SWAP                                                │
│     └─> Either party calls executeSwap(roomId)                  │
│         Atomic on-chain swap via relayer                        │
│         Returns: txSignature                                    │
│                                                                 │
│  [OPTIONAL] LOCKUP FLOW                                         │
│     └─> Before step 4, Party A can proposeLockup(roomId, secs)  │
│     └─> Party B must acceptLockup(roomId) to continue           │
│     └─> After execute, locked tokens claimed via claimLockedTokens │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

API Reference

Room Management

| Method | Parameters | Returns | Description | |--------|------------|---------|-------------| | createRoom(options?) | { inviteCode?: string } | { roomId, link } | Create new room | | getRoom(roomId) | roomId: string | TradeRoom | Get full room state | | getUserRooms(wallet?) | wallet?: string | TradeRoom[] | List your rooms | | joinRoom(roomId, inviteCode?) | roomId, inviteCode? | { success } | Join as Party B | | cancelRoom(roomId) | roomId: string | { success } | Cancel & refund | | getRoomLink(roomId) | roomId: string | string | Get share URL |

Trading

| Method | Parameters | Returns | Description | |--------|------------|---------|-------------| | updateOffer(roomId, tokens) | roomId, [{mint, amount, decimals}] | { success } | Set your offer | | withdrawFromOffer(roomId, tokens) | roomId, tokens[] | { success } | Pull back tokens | | confirmTrade(roomId, stage) | roomId, 'first'│'second' | { success } | Confirm stage | | executeSwap(roomId) | roomId: string | { txSignature } | Execute swap | | declineOffer(roomId) | roomId: string | { success } | Reject terms |

Lockups (Anti-Dump)

| Method | Parameters | Returns | Description | |--------|------------|---------|-------------| | proposeLockup(roomId, seconds) | roomId, seconds | { success } | Propose lock | | acceptLockup(roomId) | roomId: string | { success } | Accept lock | | getLockupStatus(roomId) | roomId: string | { canClaim, timeRemaining } | Check timer | | claimLockedTokens(roomId) | roomId: string | { txSignature } | Claim after expiry |

Utility

| Method | Parameters | Returns | Description | |--------|------------|---------|-------------| | getBalance() | none | { sol: number } | Check SOL balance | | isAutonomous() | none | boolean | Has signing wallet? | | getWebSocketUrl() | none | string | Get WS endpoint |

WebSocket Real-Time Updates

Don't poll. Subscribe.

Instead of repeatedly calling getRoom(), connect to WebSocket for instant updates:

Endpoint: wss://poseidon.cash/ws/trade-room

Subscribe to Room Events

const { unsubscribe } = await client.subscribeToRoom(roomId, (event) => {
  switch (event.type) {
    case 'join':
      console.log('Counterparty joined!');
      break;
    case 'offer':
      console.log('Offer updated:', event.data.tokens);
      break;
    case 'confirm':
      console.log('Confirmation received');
      break;
    case 'execute':
      console.log('Swap complete! TX:', event.data.txSignature);
      break;
    case 'cancel':
      console.log('Trade cancelled');
      break;
  }
});

...