Metaplex

快速入门

读取代理数据

Last updated July 8, 2026

在注册后读取并验证代理身份——可直接通过 SDK 在链上读取，也可通过已索引的 DAS API 读取。

Summary

代理身份可通过 Agent Registry SDK 在链上读取，或通过 DAS API 读取已索引字段。

  • 链上（SDK） — 检查注册、检查 AgentIdentity 插件、获取 ERC-8004 文档、派生 Asset Signer PDA
  • 已索引（DAS） — 从 getAsset 读取 is_agent、asset_signer 和 agent_token；通过 searchAssets 发现代理
  • 相同钱包地址 — findAssetSignerPda 与 DAS 的 asset_signer 返回相同的 PDA

Quick Start

本页涵盖 SDK 注册检查、注册文档、钱包 PDA 以及 DAS 已索引的代理字段。

跳转到： 检查注册 · 注册文档 · 代理钱包 · 通过 DAS 读取

  1. 单个代理，完整详情 — 使用 safeFetchAgentIdentityV1 和 fetchAsset（见下方 SDK 章节）
  2. 单个代理，已索引字段 — 使用 Core 资产地址调用 getAsset（见下方 DAS 章节）
  3. 发现代理 — 使用 isAgent: true 调用 searchAssets，或按 agentToken / assetSigner 过滤

检查注册 {#check-registration}

安全获取方法在身份不存在时返回 null 而不是抛出异常，这对于检查资产是否已注册很有用：

1import {

2  safeFetchAgentIdentityV1,

3  findAgentIdentityV1Pda,

4  mplAgentIdentity,

5} from '@metaplex-foundation/mpl-agent-registry'

6import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

7import { publicKey } from '@metaplex-foundation/umi'

8

9const umi = createUmi('https://api.mainnet-beta.solana.com').use(mplAgentIdentity())

10const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

11

12const pda = findAgentIdentityV1Pda(umi, { asset: assetPublicKey })

13const identity = await safeFetchAgentIdentityV1(umi, pda)

14

15console.log('Registered:', identity !== null)

16

17// Registered: true

从种子获取

您也可以直接从资产的公钥获取身份，无需手动派生 PDA：

1import {

2  fetchAgentIdentityV1FromSeeds,

3  mplAgentIdentity,

4} from '@metaplex-foundation/mpl-agent-registry'

5import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

6import { publicKey } from '@metaplex-foundation/umi'

7

8const umi = createUmi('https://api.mainnet-beta.solana.com').use(mplAgentIdentity())

9const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

10

11// Throws if the identity account does not exist — use safeFetchAgentIdentityV1 for unregistered assets.

12const identity = await fetchAgentIdentityV1FromSeeds(umi, {

13  asset: assetPublicKey,

14})

15

16console.log('Identity:', identity)

17

18// Identity: { ... }

验证 AgentIdentity 插件

注册会将 AgentIdentity 插件附加到 Core 资产。您可以直接从获取的资产中读取它来检查注册 URI 和生命周期钩子：

1import { fetchAsset, mplCore } from '@metaplex-foundation/mpl-core'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3import { publicKey } from '@metaplex-foundation/umi'

4

5const umi = createUmi('https://api.mainnet-beta.solana.com').use(mplCore())

6const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

7

8const assetData = await fetchAsset(umi, assetPublicKey)

9const agentIdentity = assetData.agentIdentities?.[0]

10

11console.log(agentIdentity?.uri)

12console.log(agentIdentity?.lifecycleChecks?.transfer)

13console.log(agentIdentity?.lifecycleChecks?.update)

14console.log(agentIdentity?.lifecycleChecks?.execute)

15

16// https://example.com/agent-registration.json

17// { __kind: 'Listen' }

18// { __kind: 'Listen' }

19// { __kind: 'Listen' }

读取注册文档 {#read-the-registration-document}

AgentIdentity 插件上的 uri 指向一个包含代理完整配置文件（名称、描述、服务端点等）的链下 JSON 文档。像其他 URI 一样获取它：

1import { fetchAsset, mplCore } from '@metaplex-foundation/mpl-core'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3import { publicKey } from '@metaplex-foundation/umi'

4

5const umi = createUmi('https://api.mainnet-beta.solana.com').use(mplCore())

6const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

7

8const assetData = await fetchAsset(umi, assetPublicKey)

9const agentIdentity = assetData.agentIdentities?.[0]

10

11if (agentIdentity?.uri) {

12  const response = await fetch(agentIdentity.uri)

13  if (!response.ok) {

14    throw new Error(`Registration document fetch failed: HTTP ${response.status}`)

15  }

16  const registration = await response.json()

17

18  console.log(registration.name)

19  console.log(registration.description)

20  console.log(registration.active)

21

22  for (const service of registration.services ?? []) {

23    console.log(service.name)

24    console.log(service.endpoint)

25    console.log(service.version)

26  }

27}

28

29// Plexpert

30// An informational agent...

31// true

32// web

33// https://metaplex.com/agent/<ASSET_PUBKEY>

34// undefined

该文档遵循 ERC-8004 代理注册标准。典型示例如下：

{

  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",

  "name": "An informational agent providing help related to Metaplex protocols and tools.",

  "description": "An autonomous agent that executes DeFi strategies on Solana.",

  "image": "https://arweave.net/agent-avatar-tx-hash",

  "services": [

    {

      "name": "web",

      "endpoint": "https://metaplex.com/agent/<ASSET_PUBKEY>"

    },

    {

      "name": "A2A",

      "endpoint": "https://metaplex.com/agent/<ASSET_PUBKEY>/agent-card.json",

      "version": "0.3.0"

    }

  ],

  "active": true,

  "registrations": [

    {

      "agentId": "<MINT_ADDRESS>",

      "agentRegistry": "solana:101:metaplex"

    }

  ],

  "supportedTrust": ["reputation", "crypto-economic"]

}

完整字段参考请参阅注册代理。

获取代理钱包 {#fetch-the-agents-wallet}

每个 Core 资产都有一个称为 Asset Signer 的内置钱包——从资产公钥派生的 PDA。不存在私钥，因此无法被盗。钱包可以持有 SOL、代币或任何其他资产。使用 findAssetSignerPda 派生地址：

1import { findAssetSignerPda, mplCore } from '@metaplex-foundation/mpl-core'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3import { publicKey } from '@metaplex-foundation/umi'

4

5const umi = createUmi('https://api.mainnet-beta.solana.com').use(mplCore())

6const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

7

8const assetSignerPda = findAssetSignerPda(umi, { asset: assetPublicKey })

9const balance = await umi.rpc.getBalance(assetSignerPda)

10

11console.log('Agent wallet:', assetSignerPda)

12console.log('Balance:', balance.basisPoints.toString(), 'lamports')

13

14// Agent wallet: 6ttUwc5VVmHeVKTddB6XM5vQgBMfw62DThuoiVEufVZq

15// Balance: 1000000 lamports

地址是确定性的，因此任何人都可以从资产的公钥派生它来发送资金或检查余额。只有资产本身才能通过委托的执行者经由 Core 的 Execute 指令为此钱包签名。

有关账户布局、PDA 派生详情和错误代码，请参阅 MPL Agent Registry 智能合约文档。

通过 DAS API 读取代理数据 {#read-agent-data-via-das-api}

DAS API 在 MPL Core 资产上索引代理字段——注册状态、钱包 PDA 和规范代币 mint——因此您无需自行解析 Core 账户即可读取这些字段。

前提条件： 一个支持 DAS 的 RPC 端点，以及在 Umi 实例上安装 @metaplex-foundation/digital-asset-standard-api。

DAS 代理响应字段

DAS 从两个链上来源派生代理元数据，并将其作为顶层响应字段返回。

字段类型出现于来源
is_agentbooleanMplCoreAsset当资产具有 AgentIdentity 外部插件时为 true
asset_signerstring (pubkey)仅 MplCoreAsset与上方 findAssetSignerPda 相同的 PDA
agent_tokenstring (pubkey)已设置时的 MplCoreAssetAgentIdentityV2 PDA mint，由 setAgentTokenV1 写入

只有 MplCoreAsset 行可以是代理（is_agent: true）。集合和组在 DAS 响应中可能包含 is_agent: false，但代理注册仅适用于单个 Core 资产。非 Core 资产（Token Metadata NFT、压缩 NFT、同质化代币）会省略全部三个字段。

已注册但未关联代币的代理返回 is_agent: true 和 asset_signer，但省略 agent_token：

getAsset response (registered, no token)
{

  "interface": "MplCoreAsset",

  "id": "84jw9dw7hMRJXFvzJXrBzVQpmVWaGUtYT7R6QhNU9qt3",

  "is_agent": true,

  "asset_signer": "6ttUwc5VVmHeVKTddB6XM5vQgBMfw62DThuoiVEufVZq",

  "external_plugins": [

    {

      "type": "AgentIdentity",

      "adapter_config": { "uri": "https://example.com/agent-registration.json" }

    }

  ]

}

执行 setAgentTokenV1 后，DAS 会包含 agent_token：

getAsset response (registered with token)
{

  "interface": "MplCoreAsset",

  "id": "84jw9dw7hMRJXFvzJXrBzVQpmVWaGUtYT7R6QhNU9qt3",

  "is_agent": true,

  "agent_token": "FakeToken11111111111111111111111111111111111",

  "asset_signer": "6ttUwc5VVmHeVKTddB6XM5vQgBMfw62DThuoiVEufVZq"

}

JSON-RPC 响应使用 snake_case（is_agent、agent_token、asset_signer）。searchAssets 请求参数使用 camelCase（isAgent、agentToken、assetSigner）；也接受 snake_case 别名。

通过 DAS 获取单个代理

当您已知 Core 资产地址时，使用 getAsset。

1import { dasApi } from '@metaplex-foundation/digital-asset-standard-api'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3import { publicKey } from '@metaplex-foundation/umi'

4

5const umi = createUmi('<DAS_ENDPOINT>').use(dasApi())

6

7const asset = await umi.rpc.getAsset(publicKey('AGENT_CORE_ASSET_ADDRESS'))

8

9if (asset.is_agent) {

10  console.log('Agent wallet (asset_signer):', asset.asset_signer)

11  console.log('Canonical token mint:', asset.agent_token ?? 'not set')

12} else {

13  console.log('Core asset is not a registered agent')

14}

15

16// Agent wallet (asset_signer): 6ttUwc5VVmHeVKTddB6XM5vQgBMfw62DThuoiVEufVZq

17// Canonical token mint: not set

搜索已注册代理

使用 isAgent: true 调用 searchAssets 以列出已注册代理。结合 interface: "MplCoreAsset" 可排除集合和组。

1import { dasApi } from '@metaplex-foundation/digital-asset-standard-api'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3

4const umi = createUmi('<DAS_ENDPOINT>').use(dasApi())

5

6const results = await umi.rpc.searchAssets({

7  isAgent: true,

8  interface: 'MplCoreAsset',

9  limit: 100,

10})

11

12for (const agent of results.items) {

13  console.log(agent.id, agent.asset_signer, agent.agent_token ?? 'no token')

14}

15

16// 1RUC5FMQherGNoLF9wDBxa1oznbq1mTieWLZ8gU8S31 DwgDrVVwcuXGU2MjHcZEcNtG2cGF6cLXCS35gPiUsU6p no token

通过代币 Mint 查找代理

代理关联其规范代币后，使用 agentToken 过滤即可从 mint 地址解析代理 Core 资产。每个代理最多只能有一个代币——绑定是永久性的。

1curl -X POST <DAS_ENDPOINT> \

2  -H "Content-Type: application/json" \

3  -d '{

4    "jsonrpc": "2.0",

5    "id": 1,

6    "method": "searchAssets",

7    "params": {

8      "agentToken": "TOKEN_MINT_ADDRESS",

9      "interface": "MplCoreAsset",

10      "limit": 1

11    }

12  }'

通过 Asset Signer 查找代理

assetSigner 过滤器可查找 execute PDA 与给定地址匹配的 Core 资产。当您已知代理钱包但不知道资产公钥时使用。

1curl -X POST <DAS_ENDPOINT> \

2  -H "Content-Type: application/json" \

3  -d '{

4    "jsonrpc": "2.0",

5    "id": 1,

6    "method": "searchAssets",

7    "params": {

8      "assetSigner": "ASSET_SIGNER_PDA_ADDRESS",

9      "limit": 1

10    }

11  }'

DAS 索引工作原理

DAS 在摄取期间从两个链上来源填充代理字段。MPL Core 资产账户更新会设置 is_agent（存在 AgentIdentity 插件时）并为 MplCoreAsset 行派生 asset_signer。Agent Registry PDA 更新会在存在 AgentIdentityV2 mint 时，为现有 MplCoreAsset 行设置 agent_token。

事件更新的字段说明
Core 资产创建或更新is_agent、asset_signer仅适用于 MplCoreAsset 行；is_agent 反映 AgentIdentity 外部插件；每个已索引 Core 资产都会派生 asset_signer
AgentIdentityV2 PDA 更新agent_token由 Agent Registry transformer 写入；仅更新现有、未销毁的 MplCoreAsset 行
资产销毁—后续 Agent Registry 更新会被忽略
过期 slot 的 PDA 重放—slot 低于 slot_updated_agent_registry 的更新会被跳过

Notes

  • Asset Signer 是一个 PDA——不存在私钥。它可以从任何来源接收资金，但只有资产本身才能通过 Core 的 Execute 指令签署发出的交易。
  • safeFetchAgentIdentityV1 对未注册资产返回 null 而不是抛出异常，使其可以安全地用于无需 try/catch 的存在性检查。
  • findAssetSignerPda 与 DAS 的 asset_signer 在每个网络上都返回相同的确定性地址。
  • 通过 setAgentTokenV1 设置后，agent_token 是永久性的——没有指令可以清除或重新分配它。
  • DAS 的 asset_signer 在 MplCoreAsset 行上返回，不仅限于已注册代理；使用 is_agent 区分代理与普通 Core NFT。
  • 已注册但未关联代币的代理会省略 agent_token——在 createAndRegisterLaunch 或手动 setAgentTokenV1 之前属于预期行为。
  • Agent Registry 更新永远不会创建新的资产行；Core 资产必须先被索引。
  • 提供商支持情况各异——请确认您的 DAS 提供商 运行支持 agent registry 的索引器。

Quick Reference

下表汇总代理相关的 DAS 过滤器、响应字段与程序 ID。

项目值
Agent Registry 程序1DREGFgysWYxLnRnKQnwrxnJQeSMk2HmGaC6whw2B2p
MPL Core 程序CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d
Asset Signer 种子['mpl-core-execute', <core_asset_pubkey>]
DAS isAgent 过滤器searchAssets 参数 isAgent: true | false
DAS agentToken 过滤器searchAssets 参数 agentToken: <mint_pubkey>
DAS assetSigner 过滤器searchAssets 参数 assetSigner: <pda_pubkey>
DAS 响应方法getAsset、getAssets、searchAssets

FAQ

agentToken 何时会出现在 DAS 响应中？

仅当代理的 AgentIdentityV2 PDA 已通过 setAgentTokenV1 设置代币 mint 时，响应中才会包含 agent_token。已注册但未关联代币的代理会省略该字段。AgentIdentityV1 PDA 不携带代币 mint，永远不会填充 agent_token。

assetSigner 与代理钱包是同一个地址吗？

是的。DAS 的 asset_signer 是 Core Asset Signer PDA——与 findAssetSignerPda 返回的地址相同。它在 MplCoreAsset 行上返回；对于已注册代理，它充当链上钱包。

能否用 isAgent 过滤非 Core 资产？

不能。is_agent、agent_token 和 asset_signer 仅适用于 MplCoreAsset。Token Metadata NFT 及其他资产类型会省略这些字段。

所有 DAS 提供商都支持代理代币字段吗？

代理代币索引随 Metaplex DAS 索引器 一起发布。第三方提供商必须运行包含 agent registry transformer 和数据库迁移的兼容索引器版本。

Glossary

以下术语出现在代理 DAS 响应与上文 SDK 读取路径中。

术语定义
AgentIdentity 插件注册 期间设置在 Core 资产上的外部插件；携带链下注册 URI
is_agentDAS 布尔值，表示 Core 资产具有 AgentIdentity 外部插件
agent_token从 AgentIdentityV2 PDA 索引的规范代币 mint 公钥；通过 setAgentTokenV1 一次性设置
asset_signer充当代理链上钱包的 Core execute PDA；由 ['mpl-core-execute', <asset>] 派生
AgentIdentityV2存储关联代币 mint 的 Agent Registry PDA；独立于 Core 资产账户更新
Agent Registry transformerDAS 摄取处理器，将 Agent Registry PDA 更新中的 agent_token 写入现有 Core 资产行
Next
Agent 金融