Poseidon OTC

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.

Security Scan

The skill's requested permissions and runtime actions are consistent with a Solana OTC trading client, but it legitimately requires a hot wallet private key so you should only provide a burner key you control and understand the risk of autonomous execution.

Purpose & Capability

Name/description (P2P OTC swaps on Solana) align with the code and instructions: the code performs Solana RPC calls, builds program transactions against the declared OTC program ID, and calls a Poseidon backend (poseidon.cash). Requiring a burner private key is expected for autonomous on-chain actions.

Instruction Scope

SKILL.md and README describe creating rooms, updating offers, deposit/confirm flows, and atomic execute — the included code implements these flows, signs auth messages, posts to the Poseidon API, and sends on-chain transactions. The instructions do not ask the agent to read unrelated system files or exfiltrate arbitrary data.

Install Mechanism

No install script is present (instruction-only with included TypeScript source). Dependencies listed are standard Solana/web3 and crypto libs. Nothing is downloaded from untrusted URLs or redirected through shorteners in the provided manifest.

Credentials

The skill declares POSEIDON_BURNER_KEY as the primary credential and uses it to build Keypair, sign messages, and send transactions — this is proportionate to autonomous trading. The code also reads POSEIDON_API_URL, POSEIDON_RPC_URL, and POSEIDON_FRONTEND_URL (with safe defaults), but the registry's required env listing only included POSEIDON_BURNER_KEY; that small mismatch is non-malicious but should be noted. Crucially, providing POSEIDON_BURNER_KEY hands the skill full control of that wallet (it can move funds and sign arbitrary txs).

Persistence & Privilege

always:false (good). The skill is allowed to be invoked autonomously (disable-model-invocation:false) — combined with a burner private key this grants the skill capability to conduct transactions without interactive confirmation. This is expected for an autonomous OTC client but is a high-risk configuration unless you restrict the key to a small-funded burner wallet or disable autonomous invocation.

Assessment

This skill appears to do what it claims, but it requires a wallet private key (POSEIDON_BURNER_KEY). Supplying that key gives the skill the ability to sign and send on-chain transactions from that wallet — do not use your main or well‑funded keys. Suggested precautions before installing: (1) only provide a dedicated burner/private key with minimal funds, (2) prefer link/manual mode instead of autonomous mode when possible, or set disable-model-invocation (if platform allows) to prevent automated use, (3) verify the program ID (AfiRReY...LKUN) and API domain (poseidon.cash) yourself, (4) review the full source (the included src/index.ts) and test with tiny amounts on devnet/testnet first, and (5) if you must run autonomously, monitor logs and revoke the key immediately if you see unexpected activity.

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

Event Types

Event	When It Fires
full-state	Immediately on subscribe - complete room state
join	Counterparty joined the room
offer	Someone updated their offer
confirm	Someone confirmed (first or second)
lockup	Lockup proposed or accepted
execute	Swap executed successfully
cancel	Room was cancelled
terminated	Room expired or terminated
error	Something went wrong

WebSocket Actions (Faster than HTTP)

await client.sendOfferViaWs(roomId, tokens);      // Update offer
await client.sendConfirmViaWs(roomId, 'first');   // Confirm
await client.sendLockupProposalViaWs(roomId, 3600); // Propose 1hr lock
await client.sendAcceptLockupViaWs(roomId);       // Accept lock
await client.sendExecuteViaWs(roomId);            // Execute swap

Agent-to-Agent Trading Example

Scenario: Agent A wants to sell 1000 USDC for 5 SOL to Agent B

Agent A (Seller):

// 1. Create room
const { roomId } = await client.createRoom();

// 2. Set offer (1000 USDC)
await client.updateOffer(roomId, [{
  mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  amount: 1000000000,  // 1000 USDC
  decimals: 6
}]);

// 3. Share roomId with Agent B via your inter-agent protocol
// 4. Subscribe to updates
await client.subscribeToRoom(roomId, async (event) => {
  if (event.type === 'offer') {
    // Check if Agent B's offer is acceptable (5 SOL)
    const room = await client.getRoom(roomId);
    if (room.partyBTokenSlots?.[0]?.amount >= 5 * 1e9) {
      await client.confirmTrade(roomId, 'first');
    }
  }
  if (event.type === 'confirm' && room.partyBFirstConfirm) {
    await client.confirmTrade(roomId, 'second');
  }
});

Agent B (Buyer):

// 1. Join the room
await client.joinRoom(roomId);

// 2. Set offer (5 SOL)
await client.updateOffer(roomId, [{
  mint: 'So11111111111111111111111111111111111111112',  // wSOL
  amount: 5000000000,  // 5 SOL
  decimals: 9
}]);

// 3. Subscribe and react
await client.subscribeToRoom(roomId, async (event) => {
  if (event.type === 'confirm') {
    const room = await client.getRoom(roomId);
    if (room.partyAFirstConfirm && !room.partyBFirstConfirm) {
      await client.confirmTrade(roomId, 'first');
    }
    if (room.partyASecondConfirm && room.partyBSecondConfirm) {
      // Both confirmed, execute!
      await client.executeSwap(roomId);
    }
  }
});

Common Token Mints

Token	Mint Address	Decimals
USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v	6
USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB	6
wSOL	So11111111111111111111111111111111111111112	9
BONK	DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263	5

Environment Variables

POSEIDON_BURNER_KEY=<base58-private-key>  # Required for autonomous mode
POSEIDON_API_URL=https://poseidon.cash    # API endpoint (default: mainnet)
POSEIDON_RPC_URL=https://api.mainnet-beta.solana.com  # Solana RPC

Security Notes

• Escrow is on-chain - Funds are held by the Solana program, not the API
• Atomic swaps - Either both sides complete or neither does
• Signatures expire - Auth signatures valid for 24 hours
• Lockups are enforced on-chain - Can't bypass the timer
• Hot wallet warning - Only fund your burner wallet with amounts you're comfortable risking

Program ID

Mainnet: AfiRReYhvykHhKXhwjhcsXFejHdxqYLk2QLWnjvvLKUN

Links

• Website: https://poseidon.cash
• Docs: https://docs.poseidon.cash