dflow-proof-kyc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DFlow Proof

Proof is DFlow's identity-verification primitive for Solana wallets. Stripe Identity verifies the person once; Proof links that verified identity to one or more wallet addresses. Builders query a public endpoint to check status.

There are two reasons to integrate it:

Self-gating your own app — any product that needs identity-based KYC (jurisdiction-gated DeFi, regulated token sales, identity-attested access, etc.) can use Proof as a ready-made primitive.
Kalshi PM trading on DFlow — DFlow's Trading API requires Proof for Kalshi prediction-market buys. This skill is also where the matching error handling lives.

DFlow Proof是DFlow为Solana钱包打造的身份验证原语。Stripe Identity会一次性完成对用户身份的验证；Proof则将已验证的身份关联到一个或多个钱包地址。开发者可通过查询公共端点来检查验证状态。

集成它有两个用途：

为自有应用设置访问限制 —— 任何需要基于身份的KYC的产品（受司法管辖区限制的DeFi、受监管的代币发售、需身份认证的访问权限等）都可以将Proof作为现成的原语使用。
在DFlow上进行Kalshi预测市场交易 —— DFlow的交易API要求完成Proof验证才能进行Kalshi预测市场买入操作。本技能也包含对应的错误处理方案。

Prerequisites

前置条件

DFlow docs MCP (
```
https://pond.dflow.net/mcp
```
) — install per the repo README. This skill is the recipe; the MCP is the reference. Look up the deep-link signing code, the full parameter list, and user-journey diagrams via
```
search_d_flow
```
/
```
query_docs_filesystem_d_flow
```
— don't guess.
dflow
CLI (optional, only relevant for Kalshi-trading use) — install per the repo README.

DFlow docs MCP（
```
https://pond.dflow.net/mcp
```
）—— 按照仓库README安装。本技能是操作指南，MCP是参考文档。可通过
```
search_d_flow
```
/
```
query_docs_filesystem_d_flow
```
查找深度链接签名代码、完整参数列表和用户流程示意图——请勿自行猜测。
dflow
CLI（可选，仅与Kalshi交易场景相关）—— 按照仓库README安装。

Part I — Proof as a generic primitive (self-gating)

第一部分 —— 作为通用原语的Proof（自有应用访问限制）

Use this path when you need KYC for your own app, independent of Kalshi.

当你需要为自有应用实现KYC，且与Kalshi无关时，使用此流程。

Check verification status

检查验证状态

GET https://proof.dflow.net/verify/{address}

→

{ "verified": boolean }

. Public, no auth. Use it to gate features, to decide whether to show a "Verify me" CTA, or to short-circuit a restricted action.

GET https://proof.dflow.net/verify/{address}

→

{ "verified": boolean }

。公共接口，无需授权。可用于限制功能访问、决定是否显示“验证我的身份”按钮，或中止受限操作。

Redirect the user to verify (deep link)

重定向用户进行验证（深度链接）

If the wallet isn't verified, redirect the user to Proof's hosted flow. The deep link carries a signed ownership proof so Proof can link the wallet to the verified identity automatically:

URL:

https://dflow.net/proof?wallet=<addr>&signature=<sig>&timestamp=<ms>&redirect_uri=<url>

Optional:
```
email
```
,
```
projectId
```
.
Signature: user signs the exact message
```
Proof KYC verification: {timestamp}
```
(Unix ms, 13 digits) with their wallet; base58-encode the bytes.
Full signing snippet and parameter table → docs MCP, or read directly:
```
/build/proof/partner-integration
```
.

如果钱包未验证，将用户重定向到Proof的托管流程。深度链接包含签名的所有权证明，因此Proof可以自动将钱包与已验证的身份关联：

URL：

https://dflow.net/proof?wallet=<addr>&signature=<sig>&timestamp=<ms>&redirect_uri=<url>

可选参数：
```
email
```
、
```
projectId
```
。
签名：用户使用钱包对确切消息
```
Proof KYC verification: {timestamp}
```
（Unix毫秒时间戳，13位数字）进行签名；将字节以base58编码。
完整签名代码片段和参数表 → 查看docs MCP，或直接访问：
```
/build/proof/partner-integration
```
。

Handle the return

处理返回流程

User lands back on your

redirect_uri

. Re-query

/verify/{address}

to confirm status. If

verified: true

, proceed; otherwise, surface an appropriate "verification pending / failed" message.

用户验证后会回到你的

redirect_uri

。重新调用

/verify/{address}

确认状态。如果

verified: true

，则继续操作；否则，显示合适的“验证待处理/失败”提示信息。

Part II — Kalshi PM trading (Trading API enforcement)

第二部分 —— Kalshi预测市场交易（交易API强制要求）

DFlow's Trading API enforces Proof only on Kalshi PM buys. Not sells, not redemptions, not spot, not quotes.

Three patterns, each maps to a user intent:

Proactive UX gate — at session start, call
```
/verify/{address}
```
, cache the result, and conditionally show the "Buy" button. Best UX; same primitive as Part I.
Reactive fallback — if the proactive check was skipped or is stale,
```
/order
```
will reject unverified buys with
```
unverified_wallet_not_allowed
```
(API) /
```
PROOF_NOT_VERIFIED
```
(CLI). Both error envelopes carry
```
details.deepLink
```
— redirect the user straight to it, then retry the buy after they return verified. (The CLI auto-opens the browser itself and prints the deepLink for headless environments.)
Quote-before-KYC — omit
```
userPublicKey
```
from
```
GET /order
```
to preview pricing without verification. Lets unverified users see what a buy would cost before committing to KYC.

DFlow的交易API仅在Kalshi预测市场买入时强制要求Proof验证。卖出、赎回、现货交易、报价操作均无需验证。

三种模式分别对应不同的用户需求：

主动式UX限制 —— 在会话开始时调用
```
/verify/{address}
```
，缓存结果，并根据结果决定是否显示“买入”按钮。这是最佳UX方案；使用的原语与第一部分相同。
被动式 fallback —— 如果跳过了主动检查或检查结果已过期，
```
/order
```
会拒绝未验证的买入请求，并返回
```
unverified_wallet_not_allowed
```
（API）/
```
PROOF_NOT_VERIFIED
```
（CLI）错误。两种错误信息中都包含
```
details.deepLink
```
——直接将用户重定向到该链接，待用户完成验证返回后重试买入操作。（CLI会自动打开浏览器，并为无头环境打印深度链接。）
先报价后KYC —— 在
```
GET /order
```
请求中省略
```
userPublicKey
```
，即可在无需验证的情况下预览定价。让未验证用户在决定完成KYC前查看买入成本。

What to ASK the user (and what NOT to ask)

需要询问用户的内容（以及无需询问的内容）

Ask if missing:

What are they using Proof for? Self-gating their own app / Kalshi PM trading / both.

Self-gating → only
```
/verify/{address}
```
+ deep-link flow matters. Skip trade-API error handling.

Kalshi trading → same flow, plus handle

unverified_wallet_not_allowed

PROOF_NOT_VERIFIED

details.deepLink

/order

time.

Both → superset of the Kalshi path.

Wallet pubkey — the address to verify / check.
App's callback URL (
```
redirect_uri
```
) — where Proof sends the user after verification.
Web or native mobile — changes the redirect_uri guidance (universal / app links for mobile; see Gotchas).

Do NOT ask about:

API key —
```
/verify/{address}
```
is public, no auth. Proof itself has no API key concept.
RPC / signing for trading — that's
```
dflow-kalshi-trading
```
. This skill just does the verification piece.

若缺少以下信息，请询问用户：

他们使用Proof的用途是什么？ 为自有应用设置访问限制 / Kalshi预测市场交易 / 两者皆有。

自有应用访问限制 → 只需关注
```
/verify/{address}
```
+ 深度链接流程。无需处理交易API错误。

Kalshi交易 → 流程相同，还需在

/order

环节处理

unverified_wallet_not_allowed

PROOF_NOT_VERIFIED

details.deepLink

错误。

两者皆有 → 包含Kalshi场景的所有流程。

钱包公钥 —— 需要验证/检查的钱包地址。
应用回调URL（
```
redirect_uri
```
）—— 用户完成验证后Proof跳转回的地址。
Web端还是原生移动端 —— 会影响redirect_uri的设置建议（移动端使用通用链接/应用链接；参考注意事项）。

无需询问的内容：

API密钥 ——
```
/verify/{address}
```
是公共接口，无需授权。Proof本身没有API密钥的概念。
交易相关的RPC/签名 —— 这属于
```
dflow-kalshi-trading
```
的范畴。本技能仅负责验证环节。

Gotchas (the docs MCP won't volunteer these)

注意事项（docs MCP不会主动提及）

Proof is enforced on Kalshi PM buys, not spot swaps. Don't state "all DFlow trades need KYC" — they don't.
Buys only, not sells or redemptions. Even on Kalshi, selling an outcome token or redeeming a winner needs no KYC.
Proof doesn't verify age. Stripe Identity captures name, address, email, and government-issued ID, but Proof does not currently check or expose date-of-birth. Don't use Proof for age gating — you won't get what you need.
Enforced on both dev and prod. Many agents assume dev is unprotected; it isn't.
Proof is usable outside Kalshi. Don't default to thinking "Proof = Kalshi KYC" — any builder who needs identity-gating can use it. Same primitive, same endpoint.
Redirect URI scheme restrictions. Proof only redirects to
```
https:
```
,
```
chrome-extension:
```
, and
```
moz-extension:
```
URLs. Custom schemes (
```
myapp://callback
```
) fail silently — no redirect, no error. Native mobile → universal links (iOS) / app links (Android), which are
```
https:
```
URLs that deep-link into the app.
The public endpoint is booleanized.
```
/verify/{address}
```
returns
```
{ verified: true | false }
```
. There's no
```
pending
```
/
```
failed
```
/
```
unverified
```
distinction — everything non-verified collapses to
```
false
```
. If you need those states for UX, infer them from your own session state (did the user come back from Proof?), not from the public check.
Cache
true
, not
false
. Once verified, a wallet stays verified; caching avoids the per-trade check. But unverified is volatile — never cache it, because it flips the moment the user completes the flow.
For Kalshi buys, DFlow is authoritative.
```
/order
```
checks verification server-side internally, so you don't need your own backend re-check just to gate a buy — the API won't let an unverified wallet through either way. Client-side caching is fine purely as a UX hint (to hide the Buy button).
For self-gating your own app, verify server-side. If your backend is the thing enforcing a KYC-gated feature (not DFlow's API), don't trust a client's cached status. Re-query
```
/verify/{address}
```
from your backend before unlocking the gated action.
Embedded wallets work. Privy, Turnkey, etc., as long as the wallet supports
```
signMessage
```
.
One verified identity → unlimited wallets. No cap. A user who verified on wallet A can link wallet B, C, D, and onward without re-doing ID + liveness — just a fresh ownership signature from each new wallet.
Free + Stripe Identity under the hood. No fee to builders or users. Users complete Stripe's document + liveness flow.
Proof is not geoblocking. KYC ≠ jurisdictional restriction. Kalshi PM trading requires both — geoblocking logic lives inline in
```
dflow-kalshi-trading
```
, not here.

Proof仅在Kalshi预测市场买入时强制要求，现货兑换无需验证。不要表述为“所有DFlow交易都需要KYC”——事实并非如此。
仅买入需要验证，卖出和赎回无需。即使在Kalshi平台，卖出结果代币或赎回获胜代币也无需KYC。
Proof不验证年龄。Stripe Identity会收集姓名、地址、邮箱和政府签发的身份证件，但Proof目前不检查或暴露出生日期。请勿将Proof用于年龄限制——无法满足需求。
开发环境和生产环境均强制执行。许多工具会假设开发环境不受保护，但实际并非如此。
Proof可在Kalshi之外使用。不要默认认为“Proof = Kalshi KYC”——任何需要身份限制的开发者都可以使用它。同一原语，同一端点。
重定向URI协议限制。Proof仅支持重定向到
```
https:
```
、
```
chrome-extension:
```
和
```
moz-extension:
```
协议的URL。自定义协议（如
```
myapp://callback
```
）会静默失败——既不跳转，也不报错。原生移动端需使用通用链接（iOS）/应用链接（Android），这些都是可深度链接到应用的
```
https:
```
URL。
公共端点仅返回布尔值。
```
/verify/{address}
```
返回
```
{ verified: true | false }
```
。没有“待处理”/“失败”/“未验证”的区分——所有未验证状态都归为
```
false
```
。如果需要在UX中区分这些状态，请从自身会话状态推断（用户是否从Proof返回？），而非依赖公共检查结果。
缓存
true
结果，不要缓存
false
结果。钱包一旦验证通过，状态会保持有效；缓存可避免每次交易都检查。但未验证状态是可变的——不要缓存，因为用户完成验证后状态会立即变为已验证。
对于Kalshi买入，DFlow是权威方。
```
/order
```
会在服务器端内部检查验证状态，因此你无需在自己的后端重新检查来限制买入——API同样会阻止未验证的钱包进行操作。客户端缓存仅作为UX提示（隐藏买入按钮）即可。
对于自有应用的访问限制，请在服务器端验证。如果你的后端是执行KYC限制功能的主体（而非DFlow的API），不要信任客户端的缓存状态。在解锁受限操作前，务必从后端重新调用
```
/verify/{address}
```
。
嵌入式钱包兼容。Privy、Turnkey等嵌入式钱包均可使用，只要钱包支持
```
signMessage
```
功能。
一个已验证身份可关联无限个钱包。无数量上限。已在钱包A完成验证的用户，可关联钱包B、C、D等，无需重新完成身份验证和活体检测——只需为每个新钱包生成新的所有权签名即可。
免费使用，底层基于Stripe Identity。开发者和用户均无需付费。用户需完成Stripe的文档+活体检测流程。
Proof不等于地理封锁。KYC≠司法管辖区限制。Kalshi预测市场交易同时需要两者——地理封锁逻辑内置在
```
dflow-kalshi-trading
```
中，而非本技能。

When something doesn't fit

特殊情况处理

Defer to the docs MCP for full reference — specifically:

```
/build/proof/partner-integration
```
— deep-link code (signature generation, URL building), caching sample, handling edge cases (signature expiration, user cancellation, network errors), security guidance.
```
/build/proof/user-journeys
```
— diagrams for new-direct, new-from-partner, and returning-user flows.
```
/build/proof-api/verify-address
```
— the single public endpoint's reference.
```
/build/faqs
```
— Proof + embedded wallets, Proof + dev endpoints, redirect debugging.

如需完整参考，请查阅docs MCP，特别是：

```
/build/proof/partner-integration
```
—— 深度链接代码（签名生成、URL构建）、缓存示例、边缘情况处理（签名过期、用户取消、网络错误）、安全指南。
```
/build/proof/user-journeys
```
—— 新用户直接访问、从合作方跳转、返回用户的流程示意图。
```
/build/proof-api/verify-address
```
—— 公共端点的参考文档。
```
/build/faqs
```
—— Proof与嵌入式钱包、Proof与开发端点、重定向调试相关问题。

Sibling skills

关联技能

```
dflow-kalshi-trading
```
— places the actual orders that require Proof. Geoblocking policy also lives here.
```
dflow-kalshi-portfolio
```
— view positions / P&L (no Proof required for reading).
```
dflow-spot-trading
```
— non-Kalshi swaps; no Proof required, ever.

```
dflow-kalshi-trading
```
—— 处理需要Proof验证的实际下单操作。地理封锁策略也在此技能中。
```
dflow-kalshi-portfolio
```
—— 查看持仓/盈亏（查看无需Proof验证）。
```
dflow-spot-trading
```
—— 非Kalshi兑换操作；永远无需Proof验证。