Pi Network

如何在 Pi 测试网上创建代币？

Thu, 04 Dec 2025 16:28:27 +0800

先决条件

您需要两个测试网钱包来创建代币。请在 Pi 钱包中创建它们，并在 Pi 测试网上激活它们。您可以从钱包的设置页面访问钱包的私钥。

令牌是如何创建的

在 Pi 区块链上，如果钱包想要处理某个代币，必须先通过“建立信任线”来信任该代币。这可以保护钱包免受来自未知发送者的未经授权的代币的侵害。当特定代币的信任线首次建立时，该代币就会被写入链上。您将在下面的示例中详细了解其工作原理。

步骤

假设我们要创建“TestToken”。在本文档中，我们将把先决条件中的两个钱包分别称为“发行者”和“分发者”。

1.从“分发者”钱包建立一条指向“TestToken”的信任线。由于这是首次为“TestToken”建立信任线，因此该代币现在已被链上识别。但是，由于该代币尚未铸造，因此其总供应量尚不存在。

2.现在，您可以通过“发行方”钱包使用“支付”操作向“分发方”钱包发送一定数量的代币，这本质上就是“铸造”代币。正如我们在上一节中了解到的，钱包需要信任线才能处理特定的代币。当注册新代币时，第一个建立信任线的钱包自然而然地成为分发方钱包，因为它是唯一可以持有该代币的钱包，直到其他钱包也建立起对该代币的信任线为止。

代币铸造 - 代码示例

以下是一个 NodeJS 代码片段，展示了上述步骤。这是一个非常简单的示例，仅展示了流程的概要，您的生产代码应该负责错误处理。请注意，您需要将 Stellar SDK 作为依赖项。

const StellarSDK = require("@stellar/stellar-sdk");
const server = new StellarSDK.Horizon.Server("https://api.testnet.minepi.com");
const NETWORK_PASSPHRASE = "Pi Testnet";
// prepare keypairs
const issuerKeypair = StellarSDK.Keypair.fromSecret(""); // use actual secret key here
const distributorKeypair = StellarSDK.Keypair.fromSecret(""); // use actual secret key here
// define a token
// token code should be alphanumeric and up to 12 characters, case sensitive
const customToken = new StellarSDK.Asset("TestToken", issuerKeypair.publicKey());
const distributorAccount = await server.loadAccount(distributorKeypair.publicKey());
// look up base fee
const response = await server.ledgers().order("desc").limit(1).call();
const latestBlock = response.records[0];
const baseFee = latestBlock.base_fee_in_stroops;
// prepare a transaction that establishes trustline
const trustlineTransaction = new StellarSDK.TransactionBuilder(distributorAccount, {
  fee: baseFee,
  networkPassphrase: NETWORK_PASSPHRASE,
  timebounds: await server.fetchTimebounds(90),
})
  .addOperation(StellarSDK.Operation.changeTrust({ asset: customToken, limit: undefined }))
  .build();
trustlineTransaction.sign(distributorKeypair);
// submit a tx
await server.submitTransaction(trustlineTransaction);
console.log("Trustline created successfully");
//====================================================================================
// now mint TestToken by sending from issuer account to distributor account
const issuerAccount = await server.loadAccount(issuerKeypair.publicKey());
const paymentTransaction = new StellarSDK.TransactionBuilder(issuerAccount, {
  fee: baseFee,
  networkPassphrase: NETWORK_PASSPHRASE,
  timebounds: await server.fetchTimebounds(90),
})
  .addOperation(
    StellarSDK.Operation.payment({
      destination: distributorKeypair.publicKey(),
      asset: customToken,
      amount: "100000", // amount to mint
    })
  )
  .build();
paymentTransaction.sign(issuerKeypair);
// submit a tx
await server.submitTransaction(paymentTransaction);
console.log("Token issued successfully");
// checking new balance of the distributor account
const updatedDistributorAccount = await server.loadAccount(distributorKeypair.publicKey());
updatedDistributorAccount.balances.forEach((balance) => {
  if (balance.asset_type === "native") {
    console.log(`Test-Pi Balance: ${balance.balance}`);
  } else {
    console.log(`${balance.asset_code} Balance: ${balance.balance}`);
  }
});

如何在 Pi Wallet 上列出

虽然代币已在 Pi 测试网上铸造，但只有在 Pi 服务器识别后才会显示在 Pi 钱包中。要将其添加到 Pi 钱包，您需要将您的主域名关联到您的发行方账户，您可以使用“setOptions”操作进行设置。

在设置“主域名”之前，如果您检查您的令牌"https://api.testnet.minepi.com/assets?asset_code=<YOUR_TOKEN_CODE>&asset_issuer=<YOUR_TOKEN_ISSUER>"，您会注意到“toml”部分下的“href”为空。

...
"_links": {
  "toml": {
    "href": ""
  }
}
...

现在您可以参考下面的示例，将主域名设置为颁发者帐户。

设置主域名 - 代码示例

每次交易时，都需要加载账户以使用账户的最新序列号，这一点非常重要。

const issuerAccount = await server.loadAccount(issuerKeypair.publicKey());
const setOptionsTransaction = new StellarSDK.TransactionBuilder(issuerAccount, {
  fee: baseFee,
  networkPassphrase: NETWORK_PASSPHRASE,
  timebounds: await server.fetchTimebounds(90),
})
  .addOperation(StellarSDK.Operation.setOptions({ homeDomain: "example.com" })) // replace with your actual domain
  .build();
setOptionsTransaction.sign(issuerKeypair);
await server.submitTransaction(setOptionsTransaction);
console.log("Home Domain is set successfully.");

设置“主页域名”后，如果您再次查看同一页面，您会注意到它现在显示您的主页域名，如下所示。

...
"_links": {
  "toml": {
    "href": "https://<YOUR_DOMAIN>/.well-known/pi.toml"
  }
}
...

除了上述内容外，"home_domain"您的发卡机构帐户页面上还会出现一个新字段（"https://api.testnet.minepi.com/accounts/<ISSUER_ACCOUNT_PUBLIC_KEY>"）。

正如您可能预料到的，您需要pi.toml在指定位置托管一个文件https://<YOUR_DOMAIN>/.well-known/pi.toml。该文件包含您的令牌的一些元数据，用于证明该令牌与该域名关联。请确保此文件可公开访问，并以纯文本形式托管在您的服务器上（content-type: text/plain）。

pi.toml 的内容

有几个与令牌相关的必填字段需要供 Pi 服务器验证。以下是一个示例。由于这是一个表示所有元数据的文本文件，您可以添加其他字段。

如果一个发行方发行多个代币，则每个代币都应该有自己的[[CURRENCIES]]部分。

[[CURRENCIES]]
code="TestToken"
issuer="GCNCQ6RRVEERQXWGKB3XMRK6VGJRIHGT5UTDAAU6QEU5NL2AHFOJDYLC"
name="Pi Core Team"
desc="This is a test token that is created as an example and has no value."
image="https://image-of-your-token.com/image.png"

这些是必须核实的必填字段。

代码：令牌的代码
发行者：代币发行者的公钥
名称：代币发行者的名称
desc：令牌的简单描述
图片：包含令牌图标的图片。

重要提示：

设置好主域名并完成有效pi.toml文件的托管后，经 Pi 服务器扫描，您的代币将开始出现在 Pi 钱包中。Pi 区块链上的代币会定期进行扫描，如果验证因某些原因失败（例如缺少字段或图像无法访问），之前上架的代币可能会从 Pi 钱包中移除。强烈建议您正确缓存您的文件pi.toml。image
您的pi.toml文件image必须可通过访问https，否则验证将失败。

代币分发

代币分发方式有多种，但这里我们将介绍两种简单的方法。请注意，接收者必须将您的代币添加到 Pi 钱包中。当您的代币出现在 Pi 钱包中时，用户可以在 Pi 钱包用户界面中选择您的代币并启用（即创建信任线）。

1.直接支付流

假设接收方已为您的代币创建了信任线，您可以像在代币铸造 - 代码示例部分中从发行方账户到分销商账户那样，使用分销商账户的“支付”操作。

2.创建流动性池

由于用户可以通过水龙头访问 Test-Pi，另一种方法是创建一个流动性池 (LP)，让用户直接从池中获取一些您的代币。

a. 在 Pi 钱包中，前往“代币”页面，然后点击“流动性池”图标。选择“我的池”选项卡，在底部您会看到可以创建新的流动性池。选择“Test-Pi”以及您想要的代币和数量。创建完成后，该池将显示在“全部”选项卡下。

b. 作为用户，假设我已经将您的代币添加到我的钱包，我可以前往“代币”页面，然后点击“兑换”图标。该From代币名为“Test-Pi”，也To就是您的代币。选择代币后，我可以输入想要兑换的数量。输入数量后From，相应的To金额会自动填充。然后我就可以进行兑换，并获得您的代币了。

其他资源

如果您想了解更多高级功能，请查看以下页面。强烈建议您点击最后一个链接，配置最大发行量并锁定发行账户。

精彩的文档

Stellar JS SDK 文档

代币最佳实践

平台 API

Thu, 04 Dec 2025 16:16:40 +0800

平台 API 允许您读取和写入与部署在 Pi 应用平台上的应用及其用户相关的 Pi 服务器的数据。

概述

基本路径：

最新版本的平台 API 可在以下网址获取api.minepi.com/v2：

关于 API 版本控制的说明：

平台 API 目前版本为 v2。我们将尽可能避免对 API 版本进行任何重大更改，并将重大更改作为新的主要版本发布。但是，如有必要（例如安全或隐私修复），我们可能会在不另行通知的情况下对现有版本进行重大更改。

授权

平台 API 支持两种不同的授权机制。

访问令牌授权

某些 API 调用需要您提供用户的访问令牌才能访问资源。这些调用通常与用户数据相关（例如/me：）。可以使用以下 Authorization 标头访问这些端点：

Authorization: Bearer <user access token>

这些端点可以从后端/服务器应用程序访问，也可以从前端/客户端应用程序访问。

服务器 API 密钥授权

由于各种原因，您的后端/服务器应用程序必须发出一些 API 调用。可以使用以下 Authorization 标头访问这些端点：

Authorization: Key <your Server API Key>

警告：服务器 API 密钥仅供服务器使用。

您的服务器 API 密钥必须保存在您的服务器上，不得发送给客户端（请勿在客户端 JavaScript 代码中使用它）。将来，您的服务器 API 密钥可能会启用应用程序本身的敏感操作，而这些操作不应被用户允许执行。允许用户访问您的服务器 API 密钥会造成严重的安全漏洞。

API 参考

验证

访问用户的资源：

获取用户信息，包括用户已同意与您的应用共享的用户信息。

GET /me

授权方式：访问令牌
响应类型：UserDTO

通过将用户的访问令牌发送到后端并使用此 API 端点来验证使用前端 SDK 获取的数据（恶意用户可能会篡改请求并向您发送错误数据），以验证令牌的有效性和用户的身份。

访问令牌是很长的随机字符串，如果令牌被篡改，则请求将失败（401 HTTP 错误代码）（被篡改的令牌不属于任何真实用户）。

付款

有两种不同的付款方式。

U2A（用户到应用）
A2U（应用到用户）

创建付款（U2A）：

如果付款类型为 U2A，请使用createPayment客户端 JavaScript SDK 的方法创建付款。更多详情请参阅“付款”部分。

创建付款（A2U）：

POST /payments

授权方式：服务器 API 密钥
响应类型：PaymentDTO

请求正文示例：

{
  "payment": {
    "amount": 1,
    "memo": "From app to user test",
    "metadata": {"test": "test metadata"},
    "uid": "a1111111-aaaa-bbbb-2222-ccccccc3333d"
  }
}

收到付款：

获取付款信息。

GET /payments/{payment_id}

授权方式：服务器 API 密钥
响应类型：PaymentDTO

批准付款：

服务器端批准：将付款标记为已批准，使用户能够将交易提交到区块链。

POST /payments/{payment_id}/approve

授权方式：服务器 API 密钥
响应类型：PaymentDTO

完成付款：

服务器端完成：通过向 Pi 服务器证明您的应用程序已获得付款的 txid，将付款标记为已完成，从而使用户能够关闭付款流程。

POST /payments/{payment_id}/complete

授权方式：服务器 API 密钥
响应类型：PaymentDTO

请求正文示例：

{
  "txid": "7a7ed20d3d72c365b9019baf8dc4c4e3cce4c08114d866e47ae157e3a796e9e7"
}

取消付款：

将付款标记为已取消。

POST /payments/{payment_id}/cancel

授权方式：服务器 API 密钥
响应类型：PaymentDTO

获取未完成的服务器付款：

返回处于以下两种状态之一的服务器付款（即 A2U 付款）列表：

已创建付款，但尚未进行区块链交易；
区块链交易已提交，但开发者尚未完成支付。

GET /payments/incomplete_server_payments

授权方式：服务器 API 密钥
响应类型：{ "incomplete_server_payments": Array< PaymentDTO > }

资源类型

UserDTO

{
  uid: string, // An app-specific user identifier
  credentials: {
    scopes: Array<Scope>, // a list of granted scopes
    valid_until: {
      timestamp: number,
      iso8601: string
    }
  },
  username?: string, // The user's Pi username. Requires the `username` scope.
}

PaymentDTO

{
  // Payment data:
  identifier: string, // payment identifier
  user_uid: string, // user's app-specific ID
  amount: number, // payment amount
  memo: string, // a string provided by the developer, shown to the user
  metadata: Object, // an object provided by the developer for their own usage
  from_address: string, // sender address of the blockchain transaction
  to_address: string, // recipient address of the blockchain transaction
  direction: Direction, // direction of the payment
  created_at: string, // the payment's creation timestamp
  network: AppNetwork, // a network of the payment
  // Status flags representing the current state of this payment
  status: {
    developer_approved: boolean, // Server-Side Approval
    transaction_verified: boolean, // blockchain transaction verified
    developer_completed: boolean, // Server-Side Completion
    cancelled: boolean, // cancelled by the developer or by Pi Network
    user_cancelled: boolean, // cancelled by the user
  },
  // Blockchain transaction data:
  transaction: null | { // This is null if no transaction has been made yet
    txid: string, // id of the blockchain transaction
    verified: boolean, // true if the transaction matches the payment, false otherwise
    _link: string, // a link to the operation on the Blockchain API
  },
};

RewardedAdStatusDTO

{
  "identifier": string; // the adId token returned from the Pi SDK displayAd("rewarded") method
  "mediator_ack_status": "granted" | "revoked" | "failed" | null;
  "mediator_granted_at": string | null; // ISO 8601 date string
  "mediator_revoked_at": string | null; // ISO 8601 date string

PiNet 元数据

Thu, 04 Dec 2025 15:56:51 +0800

概述

PiNet 支持代表您的应用程序公开元数据标签。此功能最实用的用途是代理负责 Facebook Open Graph 和 Twitter Cards 缩略图的 HTML 元标签，这可以进一步提升您的应用程序的知名度和增长。

目前有两种方法可以使用该功能，在本文档的后续部分，我们将分别称之为frontend流程backend。

前端元数据支持

所有在 PiNet 注册的应用默认启用元数据支持选项。该frontend选项会像机器人一样从您的应用前端抓取数据，然后代表您发布这些数据。作为开发者，您只需确保在 HTML 文件中正确添加 meta 标签，无需担心 PiNet 如何抓取它们。metatags.io 是一个用于验证 HTML 文件的实用工具。如果您想要发布的meta标签已存在于该工具中，并且您选择了相应的流程，PiNet 也应该会自动抓取它们frontend。

元frontend数据支持对于以下类型的开发者来说是一个相关的选项：

a. 对公开整个应用程序的单一元数据集感兴趣，b. 对在开发 SSR 应用程序时公开每个页面的动态元数据感兴趣。

后端元数据支持

尽管该frontend流程非常简单，且对使用 Web 和 SSR 框架的开发人员所需的自定义配置极少，但对于单页应用程序 (SPA) 开发人员来说可能不太方便。因此，PiNet 还提供了一个自定义解决方案，该方案涉及backendPiNet 与您的应用程序之间的通信，以便如果您正在开发单页应用程序，则可以使您的页面动态生成元数据标签。

先决条件

使用backend元数据支持选项之前，必须先在 Pi 开发者门户应用中启用它。打开 Pi 开发者门户应用，选择要为其启用backendPiNet 元数据支持的应用，然后进入“PiNet 设置”。在“元数据支持类型backend”字段中选择该选项，并提供有效的后端 URL。

注意：在配置 PiNet 设置之前，该应用程序必须在 Pi 开发者门户中注册一个已验证的域名。

后端设置

选择元数据支持类型后backend，PiNet 会向您的后端端点发送 GET 请求，并将/pinet/meta?pathname=<encoded-pathname>URL 的路径名作为搜索参数传递。例如，对于使用 PiNet 子域名example（可通过`<URL>` 访问https://example.pinet.com）的 PiNet 应用程序，当https://example.pinet.com/faq/1使用 `<URL>` 时，PiNet 会向 `<URL>` 发送 GET 请求https://examplebackendurl.com/pinet/meta?pathname=%2Ffaq%2F1'，并期望收到PiNetMetadataDTO形状为 `<DTO>` 的响应。如果响应的 HTTP 状态码为 200 且形状正确，PiNet 将会对外公开元数据。

类型

PiNetMetadataDTO

PiNet 要求您提供PiNetMetadataDTO类型信息。DTO 顶层的所有字段都是可选的，因此如果您不想提供所有元数据详细信息，可以省略。但是，如果提供了某些嵌套类型，则需要您提供相应的必填字段。

在以下类型别名定义中，所有?键名后紧跟 `\` 的字段都表示可选字段。例如，`\`title?:表示可选字段，而 ` title:\` 则表示必填字段。

type PiNetMetadataDTO = {
  title?: string;
  description?: string;
  authors?: null | Author | Array<Author>;
  keywords?: null | string | Array<string>;
  creator?: null | string;
  publisher?: null | string;
  formatDetection?: null | FormatDetection;
  abstract?: null | string;
  archives?: null | string | Array<string>;
  category?: null | string;
  classification?: null | string;
  openGraph?: null | OGMetadata;
  twitter?: null | TwitterMetadata;
  icons?: null | string | Array<Icon> | Icons;
};

下面列出了上述代码中使用的默认 HTML 元标记的特定类型别名PiNetMetadataDTO：

type Author = {
  url?: string;
  name?: string;
};
type FormatDetection = {
  telephone?: boolean;
  date?: boolean;
  address?: boolean;
  email?: boolean;
  url?: boolean;
};
type IconDescriptor = {
  url: string;
  type?: string;
  sizes?: string;
  color?: string;
  rel?: string;
  media?: string;
  fetchPriority?: "high" | "low" | "auto";
};
type Icon = string | IconDescriptor;
type Icons = {
  icon?: Icon | Array<Icon>;
  shortcut?: Icon | Array<Icon>;
  apple?: Icon | Array<Icon>;
  other?: IconDescriptor | Array<IconDescriptor>;
};

OpenGraph

PiNet 允许您定义 OpenGraph 特有的元数据，这些元数据将代表您公开。其主要OGMetadata类型别名是可区分联合，其中type字段是判别因子。因此，如果定义了特定元数据，则某些OGMetadata联合成员允许您指定其他属性type。

type OGMetadata =
  | OGMetadataWebsite
  | OGMetadataArticle
  | OGMetadataBook
  | OGMetadataProfile
  | OGMetadataMusicSong
  | OGMetadataMusicAlbum
  | OGMetadataMusicPlaylist
  | OGMetadataMusicRadioStation
  | OGMetadataVideoMovie
  | OGMetadataVideoEpisode
  | OGMetadataVideoTVShow
  | OGMetadataVideoOther;
type OGMetadataBase = {
  title?: string;
  description?: string;
  emails?: Array<string>;
  phoneNumbers?: Array<string>;
  faxNumbers?: Array<string>;
  locale?: string;
  alternateLocale?: Array<string>;
  images?: OGImage | Array<OGImage>;
  audio?: Array<OGAudio>;
  videos?: Array<OGVideo>;
  countryName?: string;
};
type OGMetadataWebsite = OGMetadataBase & {
  type: "website";
};
type OGMetadataArticle = OGMetadataBase & {
  type: "article";
  publishedTime?: string;
  modifiedTime?: string;
  expirationTime?: string;
  authors?: null | string | Array<string>;
  section?: null | string;
  tags?: null | string | Array<string>;
};
type OGMetadataBook = OGMetadataBase & {
  type: "book";
  isbn?: null | string;
  releaseDate?: null | string;
  authors?: null | string | Array<string>;
};
type OGMetadataProfile = OGMetadataBase & {
  type: "profile";
  firstName?: null | string;
  lastName?: null | string;
  username?: null | string;
  gender?: null | string;
};
type OGMetadataMusicSong = OGMetadataBase & {
  type: "music.song";
  duration?: null | number;
  albums?: null | string | OGAlbum | Array<OGAlbum>;
  musicians?: null | string | Array<string>;
};
type OGMetadataMusicAlbum = OGMetadataBase & {
  type: "music.album";
  songs?: null | string | OGSong | Array<string | OGSong>;
  musicians?: null | string | Array<string>;
  releaseDate?: null | string;
};
type OGMetadataMusicPlaylist = OGMetadataBase & {
  type: "music.playlist";
  songs?: null | string | OGSong | Array<string | OGSong>;
  creators?: null | string | Array<string>;
};
type OGMetadataMusicRadioStation = OGMetadataBase & {
  type: "music.radio_station";
  creators?: null | string | Array<string>;
};
type OGMetadataVideoMovie = OGMetadataBase & {
  type: "video.movie";
  actors?: null | string | OGActor | Array<OGActor>;
  directors?: null | string | Array<string>;
  writers?: null | string | Array<string>;
  duration?: null | number;
  releaseDate?: null | string;
  tags?: null | string | Array<string>;
};
type OGMetadataVideoEpisode = OGMetadataBase & {
  type: "video.episode";
  actors?: null | string | OGActor | Array<OGActor>;
  directors?: null | string | Array<string>;
  writers?: null | string | Array<string>;
  duration?: null | number;
  releaseDate?: null | string;
  tags?: null | string | Array<string>;
  series?: null | string;
};
type OGMetadataVideoTVShow = OGMetadataBase & {
  type: "video.tv_show";
};
type OGMetadataVideoOther = OGMetadataBase & {
  type: "video.other";
};

OGMetadata下面列出了上述不同联盟成员重复使用的类型别名：

type OGImageDescriptor = {
  url: string;
  secureUrl?: string;
  alt?: string;
  type?: string;
  width?: string | number;
  height?: string | number;
};
type OGImage = string | OGImageDescriptor;
type OGVideoDescriptor = {
  url: string;
  secureUrl?: string;
  alt?: string;
  type?: string;
  width?: string | number;
  height?: string | number;
};
type OGVideo = string | OGVideoDescriptor;
type OGAudioDescriptor = {
  url: string;
  secureUrl?: string;
  alt?: string;
};
type OGAudio = string | OGAudioDescriptor;
type OGActor = {
  url: string;
  role?: string;
};
type OGSong = {
  url: string;
  disc?: number;
  track?: number;
};
type OGAlbum = {
  url: string;
  disc?: number;
  track?: number;
};

Twitter 卡片

与支持 OpenGraph 协议类似，PiNet 允许您定义 Twitter 特有的元数据。其主要OGTwitterMetadata类型别名是可区分联合，其中字段是判别项。因此，如果定义了特定属性card，则某些OGTwitterMetadata联合成员允许您指定其他属性。card

type TwitterMetadata =
  | TwitterMetadataBase
  | TwitterMetadataCardSummary
  | TwitterMetadataCardSummaryLargeImage
  | TwitterMetadataCardPlayer
  | TwitterMetadataCardApp;
type TwitterMetadataBase = {
  title?: string;
  description?: string;
  creator?: string;
  creatorId?: string;
  images?: TwitterImage | Array<TwitterImage>;
};
type TwitterMetadataCardSummary = TwitterMetadataBase & {
  card: "summary";
};
type TwitterMetadataCardSummaryLargeImage = TwitterMetadataBase & {
  card: "summary_large_image";
};
type TwitterMetadataCardPlayer = TwitterMetadataBase & {
  card: "player";
  players: TwitterPlayerDescriptor | Array<TwitterPlayerDescriptor>;
};
type TwitterMetadataCardApp = TwitterMetadataBase & {
  card: "app";
};
OGTwitterMetadata下面列出了上述不同联盟成员重复使用的类型别名：
type TwitterImageDescriptor = {
  url: string;
  secureUrl?: string;
  alt?: string;
  type?: string;
  width?: string | number;
  height?: string | number;
};
type TwitterImage = string | TwitterImageDescriptor;
type TwitterPlayerDescriptor = {
  url: string;
  width: number;
  height: number;
};

PiNetMetadataDTO验证工具

这PiNetMetadataDTO可能会变得相当复杂，您可能难以验证您提供的 DTO 是否能通过 PiNet 的内部验证。您可以使用PiNet上提供的表单来验证您的 DTO 是否有效。

预付款

Thu, 04 Dec 2025 15:51:34 +0800

虽然 Pi 前端 JavaScript SDK 支持创建 U2A（用户到应用）支付，但您的应用可能还需要具备 A2U（应用到用户）支付功能。本文档将向您展示如何进行 A2U 支付。

请注意，A2U支付功能目前仅在测试网上可用。

Pi 后端 SDK

以下是可用于 A2U 支付流程的每种语言（或运行时）的 Pi 后端 SDK 列表。

语言	关联	地位
Ruby	pi-ruby	由 Pi 核心团队官方支持
Node.js	pi-nodejs	即将推出！ - 由 Pi 核心团队官方支持
Python	待定	社区维护
PHP	待定	社区维护

我们非常欢迎其他编程语言的社区维护者，如果您有兴趣维护 Pi SDK，请在PiOS 存储库中提交 PR。

支持的功能

本节列出了各个后端 SDK 支持的功能，这些功能可用于将树莓派集成到应用程序中。有关如何使用每个功能的具体信息，请参阅您在项目中使用的库的特定文档（参见上一节中的表格）。

应用内用户支付

目前A2U支付的设计涉及与Pi区块链和Pi后端的交互。Pi区块链显然是Pi交易的唯一权威来源。Pi后端用于改善终端用户体验（例如，为用户提供易于理解的钱包备注，并提供指向您应用程序的链接，同时通过不在区块链上公开这些信息来保护用户和开发者的隐私），并帮助开发者避免支付错误（例如，由于服务器故障导致的重复支付）。

好处：

更好的用户隐私：只要用户同意与您的应用程序共享钱包地址，此 API 即可安全地访问用户的钱包地址，并且鼓励开发者仅在真正打算向用户发送 π 时才访问用户的钱包，从而实现更好的隐私和用户安全。

用户钱包准确性：如果需要更改钱包，API 会返回当前用户钱包，以避免应用程序将 Pi 发送到已弃用、无法访问的用户钱包地址。

为用户和应用开发者提供更佳体验：一旦交易在区块链上发生，便无法撤销。在进行交易前通知 Pi 后端服务器您的付款信息，完成交易后再次通知后端服务器，即可在因技术问题导致交易记录未保存到数据库时，恢复相关的元数据和区块链交易信息。这样，作为第三方，Pi 后端可以帮助您避免重复付款或其他可能导致应用钱包意外清空的错误。当然，很多环节都可能出错，作为应用开发者，您是唯一负责管理应用钱包和资产的一方。此处提供的 API 按原样提供，不作任何保证。

与 Pi 生态系统更好地集成：使用 A2U API 可以让用户钱包中的付款显示为来自您的应用，而不是显示为来自未知地址的随机交易。这在未来可以带来更佳的用户体验，例如在用户钱包中提供直接链接返回您的应用，或者在用户钱包中直接显示已购买或已退货商品的缩略图图标。

付款

Thu, 04 Dec 2025 15:45:47 +0800

支付是区块链交易的封装，它使你的应用程序、Pi 区块链和 Pi 服务器能够在用户提交区块链交易以在你的应用程序中支付某些东西时保持同步。

它们使应用程序的开发者能够完全确信用户确实进行了交易，同时不必担心与 Pi 区块链交互时涉及的技术细节。

支付流程

支付创建完成后，会经历 3 个主要阶段：

支付创建和服务器端审批
用户交互和区块链交易
服务器端完成

第一阶段 - 付款创建和服务器端审批

1.createPayment您的应用前端会创建支付请求。支付流程界面会打开，但在服务器批准支付请求之前，您无法与之交互。

2.onReadyForServerApprovalJS SDK 已获取支付标识符 (PaymentID)，并将其传递给您的应用程序以进行服务器端批准。

3.您的应用前端会将支付ID发送到您的应用服务器。这部分实现由您负责。

4.服务器端审批：您的应用服务器通过 API 调用向 Pi Servers 审批付款/approve。这使得用户能够提交区块链交易。

第二阶段 - 用户交互和区块链交易

在此阶段，支付对话框变为交互式，用户可以确认交易、签名并将其提交到 Pi 区块链。

现阶段您无需做任何事情，一切都由 Pi Apps 平台和 Pi 钱包处理。

区块链交易提交后，支付流程不会关闭。您需要通过服务器端完成确认付款，您的应用才能再次显示。

第三阶段 - 服务器端完成

5.onReadyForServerCompletionJS SDK 会将区块链交易标识符 (TxID) 传递给您的应用程序前端。您需要此值来进行服务器端完成流程。

6.您的应用前端会将 TxID 发送到您的应用服务器。这部分实现由您负责。

7.服务器端完成：您的应用程序服务器通过 API 调用向 Pi 服务器确认付款/complete。这使您能够检查区块链交易是否实际发生，并告知 Pi 您已获知该交易。

8.支付流程已完成。您的应用现在对用户可见。您的应用服务器和前端可以交换数据，并更新应用界面，向用户显示确认页面。此实现由您负责。

用户可能对你的应用撒谎！
用户可能正在运行破解版的 SDK，伪装成已完成付款。如果服务器端完成的 API 调用返回非 200 错误代码，请勿将付款标记为已完成，也不要交付用户试图购买的任何商品。

简化流程

此图以简化的方式从您的应用程序的角度展示了相同的支付流程。

使用 Pi SDK 函数发起支付
由 Pi SDK 自动调用的回调函数（通知您的应用服务器需要发出批准 API 请求）
从您的应用服务器向 Pi 服务器发出 API 请求以批准付款（让 Pi 服务器知道您已了解此笔付款）。
Pi浏览器会向用户显示支付详情页面，我们正在等待用户签署交易。
由 Pi SDK 自动调用的回调函数（通知您的应用服务器需要发出完整的 API 请求）
从您的应用服务器向 Pi 服务器发出 API 请求以完成付款（告知 Pi 服务器您已完成此付款）。

Pi 开发者门户

Thu, 04 Dec 2025 11:50:19 +0800

借助 Pi SDK 和 Pi API，您可以创建可在 Pi 浏览器中运行的应用程序，供其他 Pi 用户使用。您可以在 Pi 开发者门户注册并配置您的应用程序，以便将其连接到 Pi 区块链。

如何注册您的应用

1.您可以使用 Pi 浏览器访问 Pi 开发者门户。访问pi://develop.piPi 开发者门户，网址为 [此处应填写网址]。首次进入主页时，您不会看到任何应用。要注册您的应用，请点击“新建应用”按钮。

2.首先，您需要填写 3 个必填字段。“应用网络”选项允许您选择应用连接的主机网络。根据此选项，Pi SDK 会自动将您的应用连接到相应的网络，即 Pi 主网或 Pi 测试网。请注意，一个应用一次只能连接到一个网络，并且一旦注册应用，此选项将无法更改。这意味着建议您创建两个不同的应用，一个连接到测试网用于测试，另一个连接到主网用于生产环境。

3.注册应用后，您可以查看应用的详细信息。每个应用都有自己的“应用清单”，帮助您跟踪成功设置应用所需的步骤。要查看清单，请点击“应用清单”按钮。

4.清单步骤将随着您完成每个步骤而依次解锁。第一步是配置主机选项。

5.配置好托管选项后，您会看到“应用钱包”按钮已启用，下一步是将钱包连接到应用。请按照说明创建应用并将其连接到您的应用。

6.将应用钱包连接到应用后，清单将显示相关文档，您可以参考这些文档开始使用。接下来，您可以查看并按照剩余步骤完成应用的配置。

Pi 浏览器中的测试网应用程序

如果您已将您的应用程序注册到 Pi 测试网，并且在 Pi 浏览器中访问您的应用程序，则顶部将显示黑黄相间的条纹，以表明此应用程序已连接到 Pi 测试网。

遗留项目创建于 2022 年 7 月 26 日之前

在 Pi 主网 SDK 发布之前存在的项目将指向 Pi 测试网。

此内容无法更改或更新
创建新的开发者门户项目是最佳实践。

拥有先前创建的遗留项目的开发人员和团队

1.创建一个新的开发者门户项目

选择主网 - 这将是应用程序的主网版本
URL

A.该项目应包含 Pioneers 通过 Pi 浏览器访问应用程序所需的 URL。
B.URL所有权将通过验证过程确定。

支付钱包

A.在开发者/应用钱包创建完成之前，创建新项目页面的开发者的钱包地址将用于处理所有交易。
B.如果项目页面创建者没有在主网迁移中创建的 Pi 钱包地址，则所有交易都将失败。

2.创建第二个新的开发者项目页面

选择测试网 - 这将用于测试目的
URL
A.不能与主网 URL 相同
B.必须由开发商所有。
设置所需的访问权限
本项目可以与步骤 1 中创建的主网项目关联起来。

3.将主网项目链接到 Brainstorm 项目（如果适用）

截至 2022 年 7 月，一个开发者门户项目只能链接到一个头脑风暴项目。

特殊考虑

如果一个应用团队中没有任何成员拥有主网钱包
请通过Pi 支持门户联系 Pi CT。
对于“你的问题与什么有关？”这个问题
选择“Pi 主网 SDK 钱包”
提交联系信息
Pi CT 的一名成员将跟进此事。

身份验证

Thu, 04 Dec 2025 11:48:19 +0800

本文简要介绍了如何使用 Pi SDK 和 API 接口处理用户身份验证。如需详细说明，请参阅Pi.authenticate（SDK 参考文档）和/me（API 参考文档）。

指导

以下是您在对应用用户进行身份验证时可以遵循的步骤：

1. 调用authenticate()Pi SDK

使用 Pi SDK authenticate()，您可以获取用户信息以及访问令牌。

const authRes = await window.Pi.authenticate(scopes, onIncompletePaymentFound);

/me2.使用访问令牌向 Pi API 端点发送 GET 请求进行验证

要验证您在步骤 1 中获取的数据，您需要向/mePi API 端点发送一个 GET 请求，并在请求头中包含访问令牌。如果访问令牌有效，则会返回包含UserDTO的响应。但是，如果令牌无效，则会返回 HTTP 401 未授权错误代码。

const me = await axios.get('https://api.minepi.com/v2/me', {headers: {'Authorization': `Bearer ${accessToken}}});

Pi 应用平台让开发者有机会将广告集成到他们的 Pi 应用中并获得奖励。Pi 生态系统中的所有应用都可以展示广告，但只有经过 Pi 核心团队批准的应用才能实现盈利。目前支持三种类型的广告：插页式广告、激励式广告和横幅广告。

插页式广告

插播广告是全屏广告，旨在显示在某些内容之间，通常是在自然过渡点或休息时间，例如在活动或游戏关卡之间。

从技术上讲，插页式广告可以随时显示，但请查看我们的最佳实践文档以了解更多信息。

激励广告

激励广告是全屏广告，旨在向用户展示，用户观看后可在开发者的应用内获得奖励。例如，如果您正在开发一款游戏应用，玩家的生命值耗尽但仍想继续游戏，您可以提供观看激励广告来获得额外生命值的选项。

由于激励广告旨在奖励用户，因此只有经过应用身份验证的用户才能看到它们

横幅广告

横幅广告是一种叠加式广告，会在用户使用应用时出现在屏幕顶部或底部。与全屏广告相比，横幅广告的干扰性更小，并且可以在应用使用过程中持续显示。横幅广告非常适合在不干扰用户体验的前提下，保持广告的持续曝光。

由于横幅广告始终可见，因此应将其放置在不会干扰应用程序主要内容或功能的非侵入性位置。

目前 Pi SDK不支持横幅广告，但您可以通过在开发者门户的广告设置中启用“加载中横幅广告”选项来使用此功能。加载中横幅广告会在您的应用加载时自动向用户显示。要了解更多信息，请参阅“启用加载中横幅广告”部分。

先决条件

要获得 Pi 开发者广告网络的奖励，您必须在 Pi 开发者门户网站上申请。提交申请后，Pi 核心团队将审核您的申请。

注意：根据您的应用是否已获准加入 Pi 开发者广告网络，广告模块的某些方法可能会返回略有不同的响应。这些差异在SDK 参考文档的方法定义中均有说明。

开发者广告网络应用程序

即将推出...

支持用户树莓派浏览器上的广告网络

您的用户可能正在使用旧版本的 Pi Browser，这些版本不支持开发者广告网络。您可以使用Pi.nativeFeaturesListSDK 方法确保广告网络可用，该方法会返回一个数组，列出给定 Pi Browser 版本上可用的原生功能。为了使广告正常运行，原生功能列表数组中必须包含ad_network字符串。

// you usually would check the ads support ahead of time and store the information
(async () => {
  await Pi.init({ version: "2.0" });
  const nativeFeaturesList = await Pi.nativeFeaturesList();
  const adNetworkSupported = nativeFeaturesList.includes("ad_network");
  // store adNetworkSupported for later use
})();

如果ad_network缺少该功能，并且您想向用户展示广告，您可以鼓励他们更新 Pi 浏览器。

当 promises 从Pi.Ads.requestAdandPi.Ads.showAd方法返回并解析为时"ADS_NOT_SUPPORTED"，它等同"ad_network"于原生功能列表数组中缺少该功能。

有关上面使用的 Pi SDK 方法的详细定义，请转到SDK 参考。

执行

基本用法

Pi 浏览器内部管理广告可用性策略，自动加载初始广告并在需要显示时重新加载。这旨在确保广告始终处于可显示状态。因此，在大多数情况下，您只需调用相应Pi.Ads.showAd()方法并将广告类型作为参数传递，即可向用户展示广告。

插页式广告

插页式广告易于集成，通常显示在一些过渡节点附近。例如，一款关卡制游戏应用可以每隔三关显示一次插页式广告。

// we pretend that the game app has just reached end of 3rd level according to above example
completeLevel();
if (currentLevel % 3 === 0) {
  await Pi.Ads.showAd("interstitial");
}
startNewLevel();

激励广告

激励广告旨在奖励观看广告的用户。以游戏应用为例，如果你的游戏给用户一定数量的生命值，而当他用完生命值时，你可以让他观看广告来换取一条额外的生命值。

激励广告的展示依然简单，但需要更多努力来确保安全性并验证用户是否应该获得奖励。该Pi.Ads.showAd("rewarded")方法返回一个带有额外字段的 Promise adId，您可以使用该字段根据 Pi Platform API 验证 Pi SDK 响应的有效性。

用户可能正在使用你的应用作弊！
展示激励广告后，用户应该能在您的应用中获得某种奖励。由于用户可能运行的是破解版的 SDK 并拦截您的displayAd('rewarded')方法，因此您必须在奖励用户之前，使用 Pi Platform API 验证广告的激励状态。
有关 Pi 平台 API 的文档，请参阅平台 API 文档。
mediator_ack_status只有当给定的广告有效时，才应该向用户提供奖励"granted"。

const showAdResponse = await Pi.Ads.showAd("rewarded");
if (showAdResponse.result === "AD_REWARDED") {
  // delegate rewarding user to your backend
  // e.g.:
  const result = await rewardUserForWatchingRewardedAd(showAdResponse.adId);
  if (result.rewarded === true) {
    grantUserAdditionalLive();
  }
}

启用加载横幅广告

您可以在开发者门户启用加载中横幅广告。https://develop.pinet.com在 Pi 浏览器中找到您想要启用加载中横幅广告的应用。前往“开发者广告网络”菜单项，然后选择“设置”。从那里切换“启用加载中横幅广告”选项。您可以随时禁用它。

您的应用广告相关设置已被缓存，因此要看到效果，您可能需要等待或重置 Pi Browser 以使缓存失效。

高级用法

虽然上一节中的示例足以让您的应用程序开始向用户显示广告，但您可能会发现自己需要执行其他操作，例如手动请求广告或检查广告可用性。

在某些情况下，广告加载可能会失败或中断。如果您发现某个广告不可用，可以尝试手动调用函数，Pi.Ads.requestAd()并将广告类型作为参数传递。

在其他情况下，您可能需要在调用方法之前知道广告是否已准备就绪Pi.Ads.showAd()。您可以使用Pi.Ads.isAdReady()传递广告类型作为参数的方法来检查这一点。

有关 Pi SDK 方法及其所有可能响应类型的完整定义，请查看SDK 参考文档。

插页式广告高级使用方法

// we pretend that the game app has just reached end of 3rd level according to previous example
completeLevel();
if (currentLevel % 3 === 0) {
  const isAdReadyResponse = await Pi.Ads.isAdReady("interstitial");
  if (isAdReadyResponse.ready === true) {
    return Pi.Ads.showAd("interstitial");
  }
  const requestAdResponse = await Pi.Ads.requestAd("interstitial");
  if (requestAdResponse.result !== "AD_LOADED") {
    // indicate to user that ad could not be loaded
    return;
  }
  const showAdResponse = await Pi.Ads.showAd("interstitial");
  if (showAdResponse.result !== "AD_CLOSED") {
    // indicate to user that ad could not be displayed
    return;
  }
}
startNextLevel();

如您所见，结合这 3 种方法，您可以在广告流程的任何步骤中对不愉快的路径做出反应。

激励广告高级使用

假设您已获准在您的应用上展示广告，以下是向用户展示广告的大致流程。

用户访问您的应用后，希望观看广告以获得奖励。
您的应用使用 Pi SDK 广告模块在应用内显示广告。
*有关 Pi SDK 方法的文档，请参阅SDK 参考。
使用adId从 SDK 方法获取的信息后，您需要从 Pi 服务器验证广告状态。详情请参见下一节。
*有关 Pi 平台 API 的文档，请参阅平台 API 文档。
验证通过后，即可奖励用户。

使用 Pi Platform API 进行激励广告状态验证

用户可能正在使用你的应用作弊！
展示激励广告后，用户应该能在您的应用中获得某种奖励。由于用户可能运行的是破解版的 SDK 并拦截您的displayAd('rewarded')方法，因此您必须在奖励用户之前，使用 Pi Platform API 验证广告的激励状态。
mediator_ack_status只有当给定的广告有效时，才应该向用户提供奖励"granted"。

const showRewardedAd = async () => {
  try {
    const isAdReadyResponse = await Pi.Ads.isAdReady("rewarded");
    if (isAdReadyResponse.ready === false) {
      const requestAdResponse = await Pi.Ads.requestAd("rewarded");
      if (requestAdResponse.result === "ADS_NOT_SUPPORTED") {
        // display modal to update Pi Browser
        return showAdsNotSupportedModal();
      }
      if (requestAdResponse.result !== "AD_LOADED") {
        // display modal ads are temporarily unavailable and user should try again later
        return showAdUnavailableModal();
      }
    }
    const showAdResponse = await Pi.Ads.showAd("rewarded");
    if (showAdResponse.result === "AD_REWARDED") {
      // reward user logic:
      // usually delegate rewarding user to your backend which would
      // firstly verify `adId` against Pi Platform API, then decide whether to
      // reward the user and rewarded user if the rewarded ad status is confirmed
      // e.g.:
      const result = await rewardUserForWatchingRewardedAd(adId);
      if (result.rewarded === true) {
        showRewardedModal(result.reward);
      } else {
        showRewardFailModal(result.error);
      }
    } else {
      // fallback logic
      showAdErrorModal();
    }
  } catch (err) {
    // good practice to handle any potential errors
  }
};

客户端 SDK 参考

Thu, 04 Dec 2025 10:55:24 +0800

初始化

script在所有需要调用 Pi Apps SDK 的页面中添加以下标签：

<script src="https://sdk.minepi.com/pi-sdk.js"></script>
<script>
  Pi.init({ version: "2.0" });
</script>

传递给 init 函数的 config 对象接受以下键：

version（字符串，必填） - 此项为必填项，用于确保您的应用与可能带来重大变更的新 SDK 版本兼容（在这种情况下，重大变更将在更高的版本号下实现）。
sandbox: (布尔值，可选) - 这允许您配置 SDK 在沙箱中运行。

在沙盒模式下使用 SDK：

<script src="https://sdk.minepi.com/pi-sdk.js"></script>
<script>
  Pi.init({ version: "2.0", sandbox: true });
</script>

您现在可以在沙盒环境 ( https://sandbox.minepi.com ) 中运行您的应用程序，前提是您已在开发者门户中配置了开发 URL。要配置此 URL 并查看您的沙盒 URL，请在 Pi 浏览器中打开 develop.pi 访问开发者门户。

通常情况下，如果您使用的框架或样板支持此功能，您应该能够设置沙箱标志以匹配您的开发环境。例如，大多数优秀的 Node 样板会将 `--sandbox-mode` 的值设置process.env.NODE_ENV为 `--sandbox-mode`"development"或`--sandbox "production"-mode`，您可以执行类似这样的操作： Pi.init({ version: "2.0", sandbox: <%= process.env.NODE_ENV !== 'production' %> })`--sandbox-mode`。这取决于您的设置，但通常情况下，当您的应用程序在开发环境中运行时，Pi SDK 就会以沙箱模式运行。

验证

警告：通过此方法获取的用户信息不应传递到后端，而应仅用于展示逻辑（例如显示用户名）。后端应使用平台 API 作为权威数据源。您可以使用通过此方法获取的访问令牌，通过后端请求 `/me` 端点来验证用户身份。

Pi.authenticate(scopes: Array<Scope>, onIncompletePaymentFound: Function<PaymentDTO>): Promise<AuthResult>

返回值：

type AuthResult = {
  accessToken: string;
  user: {
    uid: string;
    username: string;
  };
};

scopes

可用范围：username，，paymentswallet_address

以下是对象上各种可用键的详细说明AuthResult['user']，以及这些键存在所需的作用域：

场地	描述	所需范围
uid	用户的应用本地标识符。此标识符仅适用于此用户和此应用。如果用户撤销授予您应用的权限，此标识符将会更改。	（没有任何）
username	用户的 Pi 用户名。	username
payments	如果您的应用需要在应用和用户之间进行支付，则此项为必填项。	payments
wallet_address	在您的应用上进行身份验证的用户的钱包地址。	wallet_address

onIncompletePaymentFound

签名：(payment: PaymentDTO) => void

每次用户通过身份验证并尝试启动新的支付流程时，SDK 都会检查该用户是否存在未完成的支付。在此上下文中，未完成的支付是指已提交到 Pi 区块链但尚未处理的支付status.developer_completed（false即开发者尚未调用 /complete该支付的端点）。

如果发现付款不完整，则会调用此回调函数并传入付款信息PaymentDTO。

当此回调被调用时，您有责任完成相应的付款（您很可能需要将付款 DTO 发送到您的服务器，并根据您的业务逻辑进行处理）。您需要在向用户请求新的付款之前完成此操作。

付款

创建新的付款方式：

type PaymentData = {
  amount: number,
  memo: string,
  metadata: Object,
};
type PaymentCallbacks = {
  onReadyForServerApproval: (paymentId: string) => void,
  onReadyForServerCompletion: (paymentId: string, txid: string) => void,
  onCancel: (paymentId: string) => void,
  onError: (error: Error, payment?: PaymentDTO) => void,
};
Pi.createPayment(paymentData: PaymentData, callbacks: PaymentCallbacks): void;

该createPayment方法接受两个参数：paymentData和callbacks。

它将立即启动支付流程，该流程将在您的应用程序顶部打开，使用户能够查看付款并提交区块链交易，或拒绝该交易。

警告：同时进行多笔付款：
创建新付款时，如果当前用户已在您的应用中存在未结付款：
如果用户尚未完成区块链交易，则未完成的付款将被取消。
如果用户已经进行了区块链交易，则新的付款将被拒绝（onError将调用），并且onIncompletePaymentFound传递给该authenticate 方法的回调函数将使用现有的付款进行调用（使用此回调函数来解决此问题，例如，将先前的付款发送到您的服务器以完成服务器端操作）。

paymentData关键信息：

amount

这是用户需要向您的应用支付的金额。

例子：3.1415。

memo

本次付款的备注。此备注将在付款确认页面对用户可见。请在此处简要说明用户付款的用途。

例子：Digital kitten #1234。

metadata

您可以将此任意 JavaScript 对象附加到此付款。此对象仅供您自己使用。您应该使用此对象将此付款与您的内部业务逻辑关联起来。

例子：{ orderId: 1234, itemIds: [11, 42, 314] }

callbacks关键信息：

onReadyForServerApproval

签名：(paymentId: string) => void

当从 Pi 服务器获取到支付标识符 (paymentId) 时，会调用此函数。在审批期间，如果审批失败，此回调函数将被多次调用。如果初始尝试失败，Pi SDK 将继续大约每 10 秒调用一次该函数，直到审批计时器结束。

使用此回调函数将 paymentId 发送到您的后端进行服务器端审批。有关服务器端审批和完整支付流程的更多信息，请参阅专门的 “支付”页面。

onReadyForServerCompletion

签名：(paymentId: string, txid: string) => void

当用户将交易提交到 Pi 区块链后，会调用此函数。在完成期间，如果交易失败，此回调函数将被多次调用。如果初始尝试失败，Pi SDK 将继续大约每隔 10 秒调用一次该函数，直到完成计时器结束。

使用此回调函数将区块链交易标识符 (txid) 和支付 ID 发送到您的后端，以便进行服务器端完成。有关服务器端完成和完整支付流程的更多信息，请参阅专门的 “支付”页面。

onCancel

签名：(paymentId: string) => void

当付款被取消时（无论是用户操作还是通过程序取消），都会调用此函数。

付款可能因用户手动拒绝而取消，也可能因其他阻止情况而取消：例如，用户账户余额不足无法支付，或者同时创建了另一笔付款……

onError

签名：(error: Error, payment?: PaymentDTO) => void

当发生错误且无法完成付款时，将调用此函数。如果付款已创建，则会提供第二个参数，您可以使用该参数来调查错误。否则，只会提供第一个参数。

类型PaymentDTO

onIncompletePaymentFound这种类型用于传递给和的参数onError。

type PaymentDTO = {
  // Payment data:
  identifier: string; // payment identifier
  user_uid: string; // user's app-specific ID
  amount: number; // payment amount
  memo: string; // a string provided by the developer, shown to the user
  metadata: Object; // an object provided by the developer for their own usage
  from_address: string; // sender address of the blockchain transaction
  to_address: string; // recipient address of the blockchain transaction
  direction: Direction; // direction of the payment
  created_at: string; // payment's creation timestamp
  network: AppNetwork; // a network of the payment
  // Status flags representing the current state of this payment
  status: {
    developer_approved: boolean; // Server-Side Approval
    transaction_verified: boolean; // blockchain transaction verified
    developer_completed: boolean; // server-Side Completion
    cancelled: boolean; // cancelled by the developer or by Pi Network
    user_cancelled: boolean; // cancelled by the user
  };
  // Blockchain transaction data:
  transaction: null | {
    // This is null if no transaction has been made yet
    txid: string; // id of the blockchain transaction
    verified: boolean; // true if the transaction matches the payment, false otherwise
    _link: string; // a link to the operation on the Blockchain API
  };
};

类型Direction

开发者可以通过这种类型检查付款方向。

type Direction = "user_to_app" | "app_to_user";

类型AppNetwork

显示付款正在使用的网络。

type AppNetwork = "Pi Network" | "Pi Testnet";

类型Scope

您可以向用户请求权限。

type Scope = "username" | "payments" | "wallet_address";

原生功能列表

使用此方法可获取用户正在使用的特定版本 Pi Browser 的可用原生功能列表。某些 SDK 功能可能需要特定版本才能正常工作。

type NativeFeature = "inline_media" | "request_permission" | "ad_network";
Pi.nativeFeaturesList(): Promise<Array<NativeFeature>>;

分享对话框

打开原生共享对话框：

Pi.openShareDialog(title: string, message: string): void;

使用此方法打开原生分享对话框（由手机操作系统提供），使用户能够与朋友分享您应用中的内容。

title：所分享消息的标题
message当用户在共享流程中选择目标应用时，将发送此消息。

type ShowAdResponse =
  | {
      type: "interstitial";
      result: "AD_CLOSED" | "AD_DISPLAY_ERROR" | "AD_NETWORK_ERROR" | "AD_NOT_AVAILABLE";
    }
  | {
      type: "rewarded";
      result: "AD_REWARDED" | "AD_CLOSED" | "AD_DISPLAY_ERROR" | "AD_NETWORK_ERROR" | "AD_NOT_AVAILABLE" | "ADS_NOT_SUPPORTED" | "USER_UNAUTHENTICATED";
      adId?: string;
    };
Pi.Ads.showAd(adType: AdType): Promise<ShowAdResponse>

"AD_NOT_AVAILABLE"表示广告加载失败。
"AD_CLOSED"表示广告已成功展示并关闭。
"AD_REWARDED"表示广告已成功展示并获得奖励（仅适用于rewarded广告）。
"AD_DISPLAY_ERROR"表示广告已成功加载但未能显示。
"AD_NETWORK_ERROR"这表明用户可能遇到了网络连接问题。
"ADS_NOT_SUPPORTED"- 表示用户使用的应用版本不支持广告，
"USER_UNAUTHENTICATED"- 表示用户未经身份验证，因此无法显示激励广告（仅限rewarded广告）。

Pi 浏览器内部管理广告可用性策略，自动加载初始广告并在每次显示时重新加载。这确保广告始终处于可显示状态。然而，在极少数情况下，广告加载可能会中断，或者第三方应用可能会showAd()过快地使用方法（甚至在下一个广告准备就绪之前）。为了方便开发者处理这些情况，Pi SDK 提供了额外的方法：isAdReady()和requestAd()。

笔记：

如果您的应用已获 Pi Developer Ad Network 批准，则响应Pi.Ads.showAd('rewarded')中将包含其他adId字段，您可以使用 Pi Platform API 验证奖励状态。
如果您的申请未获 Pi 开发者广告网络批准，则响应adId中将缺少该字段Pi.Ads.showAd('rewarded')。您不应在未adId使用Pi 平台 API进行验证的情况下向用户发放奖励。

检查广告是否已准备就绪

使用此isAdReady(adType: "interstitial" | "rewarded")方法检查特定类型的广告是否可用。此方法返回一个 Promise，该 Promise 会解析为IsAdReadyResponse.

type IsAdReadyResponse = {
  type: "interstitial" | "rewarded";
  ready: boolean;
};
Pi.Ads.isAdReady(adType: AdType): Promise<IsAdReadyResponse>

Pi 浏览器内部管理广告可用性策略，自动加载初始广告并在每次显示时重新加载。这确保广告始终处于可显示状态。然而，在极少数情况下，广告加载可能会中断，或者第三方应用可能会showAd()过快地使用方法（甚至在下一个广告准备就绪之前）。为了解决此类问题，Pi SDK 提供了此方法，允许开发者显式地检查广告的可用性。

请求广告

使用requestAd(adType: "interstitial" | "rewarded")此方法请求插页式广告或激励广告。它返回一个 Promise，该 Promise 会解析为以下类型的对象RequestAdResponse：

type RequestAdResponse = {
  type: "interstitial" | "rewarded";
  result: "AD_LOADED" | "AD_FAILED_TO_LOAD" | "AD_NOT_AVAILABLE";
};

Pi.Ads.requestAd(adType: AdType): Promise<RequestAdResponse>

与广告可用性策略一样，Pi 浏览器内部会管理请求新广告以替换已显示广告的过程。虽然不能保证广告始终可用，但开发者可以使用requestAd()方法手动重试广告请求，以防请求返回的 Promise 解析isAdReady()失败false。

在系统浏览器中打开 URL

请使用系统浏览器而不是 Pi Browser 打开 URL。

Pi.openUrlInSystemBrowser(url: string): Promise<void>

该方法返回一个 Promise，当 URL 成功打开时，该 Promise 会被解析；Error如果出现错误，则会被拒绝。可能的错误信息包括：

"Failed to open URL"这表明系统浏览器无法打开该网址，可能是由于网址错误造成的。
"No minimal requirements"这表明最终用户使用的是较旧版本的Pi浏览器，该版本不支持此SDK方法。
"Unexpected error"

根据错误信息，您可以在应用程序中针对每种错误情况采取不同的处理方式。但是，如果收到"No minimal requirements"错误提示，强烈建议您鼓励用户更新 Pi 浏览器。

自述文件

Thu, 04 Dec 2025 10:50:54 +0800

前端 JavaScript SDK

JS SDK 是前端 SDK，旨在用于您的 HTML 页面或单页应用程序，并在 Pi 浏览器中运行。

为了使 SDK 能够正常运行，您需要在开发者门户上声明您的应用程序（在 Pi 浏览器中打开 develop.pi 以访问开发者门户）。

此 SDK不适用于服务器端 NodeJS 应用程序。

安装

script在所有需要调用 Pi Apps SDK 的页面中添加以下标签：

<script src="https://sdk.minepi.com/pi-sdk.js"></script>
<script>Pi.init({ version: "2.0" })</script>

这将把 Pi Network JS SDK 作为全局window.Pi对象加载。

用法

对用户进行身份验证

在成功验证用户身份之前，您无法执行任何与用户相关的操作（例如读取用户信息、向用户请求付款）。首次访问时，系统会弹出对话框，询问用户是否同意与您的应用共享其数据。

// Authenticate the user, and get permission to request payments from them:
const scopes = ['payments'];
// Read more about this callback in the SDK reference:
function onIncompletePaymentFound(payment) { /* ... */ };
Pi.authenticate(scopes, onIncompletePaymentFound).then(function(auth) {
  console.log(`Hi there! You're ready to make payments!`);
}).catch(function(error) {
  console.error(error);
});

请求付款（用户到应用）

该createPayment方法允许您请求当前用户向您的应用帐户付款。

Pi 钱包会弹出一个模态框，用户可以通过该模态框签署交易并将其提交到 Pi 区块链。

Pi.createPayment({
  // Amount of π to be paid:
  amount: 3.14,
  // An explanation of the payment - will be shown to the user:
  memo: "...", // e.g: "Digital kitten #1234",
  // An arbitrary developer-provided metadata object - for your own usage:
  metadata: { /* ... */ }, // e.g: { kittenId: 1234 }
}, {
  // Callbacks you need to implement - read more about those in the detailed docs linked below:
  onReadyForServerApproval: function(paymentId) { /* ... */ },
  onReadyForServerCompletion: function(paymentId, txid) { /* ... */ },
  onCancel: function(paymentId) { /* ... */ },
  onError: function(error, payment) { /* ... */ },
});

请求付款（应用对用户）

如果您想通过应用向用户发送 Pi，则需要使用 Pi Network 的后端 SDK，具体取决于您的后端代码所使用的编程语言。更多信息，请参阅高级支付指南。

为了确保所有相关方（您的应用程序、您的服务器、Pi 服务器和 Pi 区块链）保持同步，付款需要经过服务器端批准流程（对于用户到应用程序的付款）和/或服务器端完成流程（对于所有类型的付款）。

请参阅：

请参阅完整的付款文档，了解完整的付款流程。

请参阅高级支付文档，了解应用到用户的支付流程。

请查阅平台 API 文档，了解如何确认付款并从您的服务器进行确认。

客户端 SDK 文档详细介绍了 Pi Apps SDK 及其提供的方法。

运行演示应用程序，查看如何在应用程序代码中实现各种必需流程的示例。