NEAR Intents 1Click API 存款提交通知实战指南：POST /v0/deposit/submit 加速跨链兑换处理

导读

POST /v0/deposit/submit是 NEAR Intents 1Click API 提供的一个可选但能显著改善体验的通知端点：在你完成存款交易（Deposit TX）上链后，主动通知 1Click 交换代理，从而跳过等待链上索引发现的延迟、立即触发后续兑换流程。本文将以本仓库 api-deposit-submit.md 为核心，结合仓库中完整的 1Click API 规则族（api-quote.md、api-status.md、deposit-near.md、deposit-stellar.md、server-example.md）与 concepts.md 概念文档，讲清该端点的请求规范、各链附加字段、调用时机与整套 1Click 兑换生命周期中的位置。读完本文，你将能在自己的 swap 组件、桥接界面或服务端脚本中正确接入存款提交通知，让跨链兑换从"被动等扫描"升级为"主动催办"。

1Click 兑换生命周期中 deposit/submit 的位置

NEAR Intents 1Click API 的核心思路是：REST API 抽象了意图创建、做市商（Market Maker）协调与交易执行的全部细节，开发者只需要完成一次链上存款即可拿到兑换结果。完整集成流程见 SKILL.md：

GET /v0/tokens → POST /v0/quote (dry) → POST /v0/quote (wet) → Deposit TX → POST /v0/deposit/submit → GET /v0/status

逐段拆解对应的生命周期（见 concepts.md）：

1. 请求报价：POST /v0/quote，dry: true仅预览不生成存款地址；dry: false提交报价并返回有效期约 10 分钟的专属存款地址（depositAddress）。
2. 发送存款：把代币发送到该唯一存款地址，1Click 收到即自动开始处理。
3. 提交存款交易哈希（可选）：即本文主角POST /v0/deposit/submit，通过主动通知 1Click"我已上链"来加速处理。
4. 监控状态（可选）：GET /v0/status轮询直到终态。
5. 结果：兑换成功并送达，或失败后自动退款到refundTo地址。

可见 deposit/submit 位于"链上存款已确认"与"状态轮询"之间，是一个纯加速优化的环节，不属于必需调用。

端点规范与核心请求格式

端点描述（来自 api-deposit-submit.md）：

Optional endpoint to notify 1Click that you've sent a deposit. Speeds up processing.

即：可选端点，用于通知 1Click 你已发送存款，以加速处理。

请求格式

await fetch('https://1click.chaindefuser.com/v0/deposit/submit', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}`, }, body: JSON.stringify({ txHash: '0x123abc...', // Your deposit transaction hash depositAddress: quote.quote.depositAddress, }) });

请求体字段

关键点：depositAddress必须来自dry: false提交报价的响应。从 api-quote.md 的响应结构看，该字段位于quote对象内（quote: { depositAddress: string; depositMemo: string | null; ... }），因此在调用 submit 时通常写作quote.quote.depositAddress。

附加字段（按链区分）

这两个字段并非通用字段，而是针对特殊链场景的补充标识，后面分链详解。

调用时机：交易确认后立即调用

原文档明确给出调用时机建议：

Call immediately after your deposit transaction confirms. Not required, but improves UX.

调用时机：存款交易在链上确认后立即调用；非必需，但能改善用户体验。

原理不难理解：1Click 需要识别链上转账事件来关联到对应的报价（correlationId / depositAddress）。若不调用 submit，1Click 只能被动等待链上索引器发现存款（存在延迟）；若调用 submit，则 1Click 拿到txHash后即可立刻定向核对该笔交易，从而更快进入做市商执行阶段。

从 server-example.md 的完整服务端示例可以印证这一顺序——submitDeposit位于发送存款交易之后、状态轮询之前：

async function submitDeposit(txHash: string, depositAddress: string): Promise<void> { await fetch(`${API_BASE}/v0/deposit/submit`, { method: 'POST', headers: { 'Content-Type': 'application/json', ...(API_KEY && { Authorization: `Bearer ${API_KEY}` }), }, body: JSON.stringify({ txHash, depositAddress }), }); }

在executeSwap主流程中的调用位置：

// 2. Send deposit transaction let txHash: string; if (fromToken.contractAddress) { txHash = await client.writeContract({ address: fromToken.contractAddress as `0x${string}`, abi: erc20Abi, functionName: 'transfer', args: [quote.quote.depositAddress as `0x${string}`, BigInt(quote.quote.amountIn)], }); } else { txHash = await client.sendTransaction({ to: quote.quote.depositAddress as `0x${string}`, value: BigInt(quote.quote.amountIn), }); } // 3. Notify API (speeds up processing) await submitDeposit(txHash, quote.quote.depositAddress); // 4. Poll until complete const result = await pollStatus(quote.quote.depositAddress);

注意server-example.md中的封装还展示了两个工程细节：

• Authorization 头为条件注入（...(API_KEY && { ... })），即没有 API Key 时不带认证头——这与 concepts.md 中"注册合作伙伴门户获取 API Key 可免去 0.1%（10 基点）手续费"的说明一致；
• 调用失败不阻塞主流程：该示例未对 submit 的失败做重试或中断，因为它本身是加速手段，即使失败，后续状态轮询仍然兜底。

分链场景详解

NEAR 存款：nearSenderAccount

NEAR 链上存款走 NEP-141 代币转账。从 deposit-near.md 可以看到，NEAR 存款交易通过 Wallet Selector 调用ft_transfer（或原生 NEAR 先near_deposit包装成 wNEAR 再ft_transfer），交易哈希来自result?.[0]?.transaction?.hash。文档在结尾特别提示：

For/v0/deposit/submit, includenearSenderAccount: 'user.near'.

对应的 submit 调用（来自 api-deposit-submit.md 的 NEAR 示例）：

await fetch('https://1click.chaindefuser.com/v0/deposit/submit', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ txHash: 'Hk3ds...', depositAddress: quote.quote.depositAddress, nearSenderAccount: 'user.near', }) });

为什么 NEAR 需要nearSenderAccount？NEAR 账户体系与 EVM 地址体系不同：EVM 存款可以从txHash+depositAddress直接唯一定位发送方，而 NEAR 交易中receiver_id是存款地址、实际发款账户另有其人（sender），1Click 需要通过nearSenderAccount将交易哈希、存款地址与 NEAR 发送账户三者关联起来，加速确认ft_transfer的发起方即报价中的意图方。这是从 deposit-near.md 的交易构造结构推断出的设计意图。

Stellar 存款：memo

Stellar 是 1Click API 中唯一的MEMO 强制模式链。在 api-quote.md 中，Stellar 报价必须显式设置depositMode: 'MEMO'，响应会额外返回depositMemo；deposit-stellar.md 进一步强调：

Stellar requiresdepositMode: 'MEMO'in quote. Transaction MUST include memo or funds are lost.

Stellar 的交易中必须附加Memo.text(quote.quote.depositMemo)，否则资金可能丢失。相应地，submit 通知也必须带上这笔交易实际使用的 memo（来自 api-deposit-submit.md 的 Stellar 示例）：

await fetch('https://1click.chaindefuser.com/v0/deposit/submit', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ txHash: 'abc123...', depositAddress: quote.quote.depositAddress, memo: quote.quote.depositMemo, }) });

注意这里memo取自quote.quote.depositMemo，即必须与链上交易中实际使用的 memo 完全一致。这一关联在状态查询中同样存在——api-status.md 要求 Stellar（MEMO 模式）查询时携带&depositMemo=123456参数。由此可见，Stellar 场景下memo是贯穿报价、存款、通知、状态查询全链路的关联键，任何一环遗漏都可能导致无法定位订单。

同理，Stellar 存款使用 stroops（7 位小数）计量金额（如10000000= 1 XLM），且交易必须由@stellar/stellar-sdk的TransactionBuilder+Memo.text()构造，这部分细节在 deposit-stellar.md 中有完整代码，可作为构造txHash的参考。

EVM 存款：基础两字段即可

EVM 系（Ethereum、Base、Arbitrum、Optimism、Polygon、BSC、Avalanche、Gnosis、Berachain）存款分两类（见 deposit-evm.md）：原生代币用 wagmisendTransactionAsync({ to: depositAddress, value: BigInt(amountIn) })，ERC-20 用writeContractAsync({ ..., functionName: 'transfer', args: [depositAddress, BigInt(amountIn)] })，tokenAddress取自 token API 的contractAddress。这两类场景的 submit 都只需要基础字段txHash+depositAddress，无需附加字段。

常见注意事项与最佳实践

综合原文档与仓库中的相邻规则，接入该端点时有几个值得注意的点：

1. depositAddress 必须来自dry: false的报价：dry: true仅预览，响应不含存款地址（api-quote.md）。dry: false的报价及地址有效期约 10 分钟（deadline截止），务必在deadline前完成存款并提交通知。

2. Stellar 的 memo 必须逐字一致：报价给的depositMemo、链上Memo.text()、submit 的memo、status 查询的depositMemo四者必须完全相同，任何不一致都会影响订单定位。

3. NEAR 场景别漏nearSenderAccount：这是 NEAR 链的关联键，缺失时 1Click 无法将 NEAR 账户与交易快速绑定，加速效果会大打折扣。

4. 有 API Key 时携带 Authorization：Bearer ${apiKey}头不仅能避开 0.1% 手续费（concepts.md），也让 1Click 能按应用维度关联请求。

5. submit 失败不应阻塞主流程：它是纯加速手段，正确做法是"尽力通知 + 状态轮询兜底"。server-example.md 的轮询封装循环最多 180 次、每 2 秒一次（最长 6 分钟），遇到SUCCESS、FAILED、REFUNDED、INCOMPLETE_DEPOSIT四个终态即返回，可作为兜底参考。

6. 关注 CEX 存款警告：中心化交易所常使用中间或按用户区分的入金地址，可能不会及时认定 NEAR Intents 发来的存款；concepts.md 建议大规模转账前先用小额测试。

与相邻 API 的关系小结

综上，POST /v0/deposit/submit是 1Click API 集成中投入产出比极高的一个可选端点：只需一行txHash+depositAddress的 POST 请求，就能让跨链兑换更快进入执行阶段；再针对 NEAR 补上nearSenderAccount、针对 Stellar 补上memo，即可覆盖仓库文档涉及的全部主流链场景。完整示例代码与分链存款细节，可继续阅读本仓库的 server-example.md、deposit-evm.md、deposit-near.md、deposit-stellar.md 等文件。