Poseidon OTC 技能

给智能体的快速总结： 此技能允许你在 Solana 上与人类或其他智能体进行代币交易。你需要创建一个房间，双方将代币存入托管账户，确认后执行原子交换。无需信任——一切都在链上完成。

何时使用此技能

• - P2P 代币交易 - 直接与另一方交换任何 SPL 代币
• 智能体间交易 - 两个 AI 智能体可以自主协商并执行交易
• 大额 OTC 交易 - 通过直接交易避免 DEX 交易的滑点
• 受保护交易 - 使用锁定机制防止对手方立即抛售
• 多代币交换 - 在单次原子交易中，每方可交易最多 4 种代币

智能体快速入门

1. 初始化（需要钱包）

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

const client = new PoseidonOTC({
burnerKey: process.env.POSEIDONBURNERKEY // base58 私钥
});

2. 创建交易房间

typescript const { roomId, link } = await client.createRoom(); // 将 link 分享给对手方或另一个智能体

3. 等待对手方并设置报价

typescript // 检查房间状态 const room = await client.getRoom(roomId);

// 设置你提供的代币（以 100 USDC 为例）
await client.updateOffer(roomId, [{
mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, // USDC 铸币地址
amount: 100000000, // 100 USDC（6 位小数）
decimals: 6
}]);

4. 确认并执行

typescript // 第一次确认 = 我同意这些条款 await client.confirmTrade(roomId, first);

// 存入后，第二次确认
await client.confirmTrade(roomId, second);

// 执行原子交换
const { txSignature } = await client.executeSwap(roomId);

完整交易流程

┌─────────────────────────────────────────────────────────────────┐
│ 交易生命周期 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. 创建房间 │
│ └─> 方 A 调用 createRoom() │
│ 返回：roomId, 可分享链接 │
│ │
│ 2. 加入房间 │
│ └─> 方 B 调用 joinRoom(roomId) │
│ 房间现在包含两位参与者 │
│ │
│ 3. 设置报价 │
│ └─> 双方调用 updateOffer(roomId, tokens) │
│ 各自指定提供的代币 │
│ │
│ 4. 第一次确认（同意条款） │
│ └─> 双方调用 confirmTrade(roomId, first) │
│ 我同意用我的 X 交换你的 Y │
│ │
│ 5. 存入托管账户 │
│ └─> 代币转移到链上托管账户 │
│ （由前端或 depositToEscrow 处理） │
│ │
│ 6. 第二次确认（验证存入） │
│ └─> 双方调用 confirmTrade(roomId, second) │
│ 我看到存入完成，准备交换 │
│ │
│ 7. 执行交换 │
│ └─> 任一方调用 executeSwap(roomId) │
│ 通过中继器进行链上原子交换 │
│ 返回：txSignature │
│ │
│ [可选] 锁定流程 │
│ └─> 在步骤 4 之前，方 A 可以调用 proposeLockup(roomId, secs) │
│ └─> 方 B 必须调用 acceptLockup(roomId) 才能继续 │
│ └─> 执行后，锁定的代币通过 claimLockedTokens 领取 │
│ │
└─────────────────────────────────────────────────────────────────┘

API 参考

房间管理

方法	参数	返回	描述
createRoom(options?)	{ inviteCode?: string }	{ roomId, link }	创建新房间
getRoom(roomId)

roomId: string | TradeRoom | 获取完整房间状态 |

| getUserRooms(wallet?) | wallet?: string | TradeRoom[] | 列出你的房间 | | joinRoom(roomId, inviteCode?) | roomId, inviteCode? | { success } | 作为方 B 加入 | | cancelRoom(roomId) | roomId: string | { success } | 取消并退款 | | getRoomLink(roomId) | roomId: string | string | 获取分享 URL |

交易

方法	参数	返回	描述
updateOffer(roomId, tokens)	roomId, [{mint, amount, decimals}]	{ success }	设置你的报价
withdrawFromOffer(roomId, tokens)

roomId, tokens[] | { success } | 撤回代币 |

| confirmTrade(roomId, stage) | roomId, first│second | { success } | 确认阶段 | | executeSwap(roomId) | roomId: string | { txSignature } | 执行交换 | | declineOffer(roomId) | roomId: string | { success } | 拒绝条款 |

锁定（防抛售）

方法	参数	返回	描述
proposeLockup(roomId, seconds)	roomId, seconds	{ success }	提议锁定
acceptLockup(roomId)

roomId: string | { success } | 接受锁定 |

| getLockupStatus(roomId) | roomId: string | { canClaim, timeRemaining } | 检查计时器 | | claimLockedTokens(roomId) | roomId: string | { txSignature } | 到期后领取 |

工具

方法	参数	返回	描述
getBalance()	无	{ sol: number }	检查 SOL 余额
isAutonomous()

无 | boolean | 是否有签名钱包？ |

| getWebSocketUrl() | 无 | string | 获取 WS 端点 |

WebSocket 实时更新

不要轮询。订阅。

与其重复调用 getRoom()，不如连接 WebSocket 获取即时更新：

端点： wss://poseidon.cash/ws/trade-room

订阅房间事件

typescript const { unsubscribe } = await client.subscribeToRoom(roomId, (event) => { switch (event.type) { case join: console.log(对手方已加入！); break; case offer: console.log(报价已更新：, event.data.tokens); break; case confirm: console.log(已收到确认); break; case execute: console.log(交换完成！交易哈希：, event.data.txSignature); break; case cancel: console.log(交易已取消); break; } });

事件类型

事件	触发时机
full-state	订阅时立即触发 - 完整房间状态
join

对手方加入房间 |

| offer | 有人更新了报价 | | confirm | 有人确认（第一次或第二次） | | lockup | 锁定被提议或接受 | | execute | 交换成功执行 | | cancel | 房间被取消 | | terminated | 房间过期或终止 | | error | 出现错误 |

WebSocket 操作（比 HTTP 更快）

typescript await client.sendOfferViaWs(roomId, tokens); // 更新报价 await client.sendConfirmViaWs(roomId, first); // 确认 await client.sendLockupProposalViaWs(roomId, 3600); // 提议