identity

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Identity Skill

Provides ERC-8004 on-chain agent identity operations using the identity-registry contract. Read operations (get, get-metadata, get-last-id) work without a wallet. Write operations (register, set-uri, set-metadata, set-approval, set-wallet, unset-wallet, transfer) require an unlocked wallet.

通过身份注册合约提供ERC-8004链上Agent身份操作。读操作（get、get-metadata、get-last-id）无需钱包即可使用。写操作（register、set-uri、set-metadata、set-approval、set-wallet、unset-wallet、transfer）需要解锁的钱包。

Usage

使用方法

bun run identity/identity.ts <subcommand> [options]

bun run identity/identity.ts <subcommand> [options]

Subcommands

子命令

register

Register a new agent identity on-chain using the ERC-8004 identity registry. Returns a transaction ID. Check the transaction result to get the assigned agent ID. Requires an unlocked wallet.

bun run identity/identity.ts register [--uri <uri>] [--metadata <json>] [--fee <fee>] [--sponsored]

Options:

```
--uri
```
(optional) — URI pointing to agent metadata (IPFS, HTTP, etc.)
```
--metadata
```
(optional) — JSON array of
```
{"key": "...", "value": "<hex>"}
```
pairs (values are hex-encoded buffers)
```
--fee
```
(optional) — Fee preset (
```
low
```
,
```
medium
```
,
```
high
```
) or micro-STX amount
```
--sponsored
```
(flag) — Submit as a sponsored transaction

Output:

json

{
  "success": true,
  "txid": "0xabc...",
  "message": "Identity registration transaction submitted. Check transaction result to get your agent ID.",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xabc..."
}

在ERC-8004身份注册合约上注册新的Agent链上身份。返回交易ID。需查看交易结果以获取分配的Agent ID。需要解锁的钱包。

bun run identity/identity.ts register [--uri <uri>] [--metadata <json>] [--fee <fee>] [--sponsored]

选项：

```
--uri
```
（可选）——指向Agent元数据的URI（IPFS、HTTP等）
```
--metadata
```
（可选）——
```
{"key": "...", "value": "<hex>"}
```
格式的JSON数组（值为十六进制编码的缓冲区）
```
--fee
```
（可选）——费用预设（
```
low
```
、
```
medium
```
、
```
high
```
）或micro-STX金额
```
--sponsored
```
（标志）——作为赞助交易提交

输出：

json

{
  "success": true,
  "txid": "0xabc...",
  "message": "Identity registration transaction submitted. Check transaction result to get your agent ID.",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xabc..."
}

get

Get agent identity information from the ERC-8004 identity registry. Returns owner address, URI, and wallet if set.

bun run identity/identity.ts get --agent-id <id>

Options:

```
--agent-id
```
(required) — Agent ID to look up (non-negative integer)

Output:

json

{
  "success": true,
  "agentId": 42,
  "owner": "SP1...",
  "uri": "ipfs://...",
  "wallet": "SP2...",
  "network": "mainnet"
}

从ERC-8004身份注册合约获取Agent身份信息。返回所有者地址、URI以及已设置的钱包。

bun run identity/identity.ts get --agent-id <id>

选项：

```
--agent-id
```
（必填）——要查询的Agent ID（非负整数）

输出：

json

{
  "success": true,
  "agentId": 42,
  "owner": "SP1...",
  "uri": "ipfs://...",
  "wallet": "SP2...",
  "network": "mainnet"
}

set-uri

Update the URI for an agent identity. Caller must be the agent owner or an approved operator. Requires an unlocked wallet.

bun run identity/identity.ts set-uri --agent-id <id> --uri <uri> [--fee <fee>] [--sponsored]

Options:

```
--agent-id
```
(required) — Agent ID to update (non-negative integer)
```
--uri
```
(required) — New URI pointing to agent metadata (IPFS, HTTP, etc.)
```
--fee
```
(optional) — Fee preset (
```
low
```
,
```
medium
```
,
```
high
```
) or micro-STX amount
```
--sponsored
```
(flag) — Submit as a sponsored transaction

Output:

json

{
  "success": true,
  "txid": "0xdef...",
  "message": "Identity URI update transaction submitted.",
  "agentId": 42,
  "uri": "ipfs://newuri...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xdef..."
}

更新Agent身份的URI。调用者必须是Agent所有者或已授权的操作员。需要解锁的钱包。

bun run identity/identity.ts set-uri --agent-id <id> --uri <uri> [--fee <fee>] [--sponsored]

选项：

```
--agent-id
```
（必填）——要更新的Agent ID（非负整数）
```
--uri
```
（必填）——指向Agent元数据的新URI（IPFS、HTTP等）
```
--fee
```
（可选）——费用预设（
```
low
```
、
```
medium
```
、
```
high
```
）或micro-STX金额
```
--sponsored
```
（标志）——作为赞助交易提交

输出：

json

{
  "success": true,
  "txid": "0xdef...",
  "message": "Identity URI update transaction submitted.",
  "agentId": 42,
  "uri": "ipfs://newuri...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xdef..."
}

set-metadata

Set a metadata key-value pair for an agent identity. Value must be a hex-encoded buffer (max 512 bytes). The key

agentWallet

is reserved and will be rejected by the contract. Caller must be the agent owner or an approved operator. Requires an unlocked wallet.

bun run identity/identity.ts set-metadata --agent-id <id> --key <key> --value <hex> [--fee <fee>] [--sponsored]

Options:

```
--agent-id
```
(required) — Agent ID to update (non-negative integer)
```
--key
```
(required) — Metadata key (string)
```
--value
```
(required) — Metadata value as a hex-encoded buffer (e.g.,
```
616c696365
```
for "alice")
```
--fee
```
(optional) — Fee preset (
```
low
```
,
```
medium
```
,
```
high
```
) or micro-STX amount
```
--sponsored
```
(flag) — Submit as a sponsored transaction

Output:

json

{
  "success": true,
  "txid": "0xghi...",
  "message": "Metadata set transaction submitted.",
  "agentId": 42,
  "key": "name",
  "valueHex": "616c696365",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xghi..."
}

为Agent身份设置元数据键值对。值必须是十六进制编码的缓冲区（最大512字节）。

agentWallet

键为保留键，合约会拒绝该键的设置。调用者必须是Agent所有者或已授权的操作员。需要解锁的钱包。

bun run identity/identity.ts set-metadata --agent-id <id> --key <key> --value <hex> [--fee <fee>] [--sponsored]

选项：

```
--agent-id
```
（必填）——要更新的Agent ID（非负整数）
```
--key
```
（必填）——元数据键（字符串）
```
--value
```
（必填）——十六进制编码的元数据值（例如，"alice"对应
```
616c696365
```
）
```
--fee
```
（可选）——费用预设（
```
low
```
、
```
medium
```
、
```
high
```
）或micro-STX金额
```
--sponsored
```
（标志）——作为赞助交易提交

输出：

json

{
  "success": true,
  "txid": "0xghi...",
  "message": "Metadata set transaction submitted.",
  "agentId": 42,
  "key": "name",
  "valueHex": "616c696365",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xghi..."
}

set-approval

Approve or revoke an operator for an agent identity. Approved operators can update URI, metadata, and wallet on behalf of the owner. Only the NFT owner can call this. Requires an unlocked wallet.

bun run identity/identity.ts set-approval --agent-id <id> --operator <address> [--approved] [--fee <fee>] [--sponsored]

Options:

```
--agent-id
```
(required) — Agent ID to update (non-negative integer)
```
--operator
```
(required) — Stacks address of the operator to approve or revoke
```
--approved
```
(flag) — Grant approval (omit to revoke)
```
--fee
```
(optional) — Fee preset (
```
low
```
,
```
medium
```
,
```
high
```
) or micro-STX amount
```
--sponsored
```
(flag) — Submit as a sponsored transaction

Output:

json

{
  "success": true,
  "txid": "0xjkl...",
  "message": "Operator SP3... approved for agent 42.",
  "agentId": 42,
  "operator": "SP3...",
  "approved": true,
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xjkl..."
}

为Agent身份授权或撤销操作员权限。已授权的操作员可以代表所有者更新URI、元数据和钱包。只有NFT所有者可以调用此命令。需要解锁的钱包。

bun run identity/identity.ts set-approval --agent-id <id> --operator <address> [--approved] [--fee <fee>] [--sponsored]

选项：

```
--agent-id
```
（必填）——要更新的Agent ID（非负整数）
```
--operator
```
（必填）——要授权或撤销的操作员Stacks地址
```
--approved
```
（标志）——授予权限（省略则撤销权限）
```
--fee
```
（可选）——费用预设（
```
low
```
、
```
medium
```
、
```
high
```
）或micro-STX金额
```
--sponsored
```
（标志）——作为赞助交易提交

输出：

json

{
  "success": true,
  "txid": "0xjkl...",
  "message": "Operator SP3... approved for agent 42.",
  "agentId": 42,
  "operator": "SP3...",
  "approved": true,
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xjkl..."
}

set-wallet

Set the agent wallet for an identity to tx-sender (the active wallet address). This links the active Stacks address to the agent ID without requiring a separate signature. Caller must be the agent owner or an approved operator. Requires an unlocked wallet.

bun run identity/identity.ts set-wallet --agent-id <id> [--fee <fee>] [--sponsored]

Options:

```
--agent-id
```
(required) — Agent ID to update (non-negative integer)
```
--fee
```
(optional) — Fee preset (
```
low
```
,
```
medium
```
,
```
high
```
) or micro-STX amount
```
--sponsored
```
(flag) — Submit as a sponsored transaction

Output:

json

{
  "success": true,
  "txid": "0xmno...",
  "message": "Agent wallet set to tx-sender (SP1...) for agent 42.",
  "agentId": 42,
  "wallet": "SP1...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xmno..."
}

将Agent身份的钱包设置为交易发送者（当前激活的钱包地址）。此操作无需单独签名即可将激活的Stacks地址与Agent ID关联。调用者必须是Agent所有者或已授权的操作员。需要解锁的钱包。

bun run identity/identity.ts set-wallet --agent-id <id> [--fee <fee>] [--sponsored]

选项：

```
--agent-id
```
（必填）——要更新的Agent ID（非负整数）
```
--fee
```
（可选）——费用预设（
```
low
```
、
```
medium
```
、
```
high
```
）或micro-STX金额
```
--sponsored
```
（标志）——作为赞助交易提交

输出：

json

{
  "success": true,
  "txid": "0xmno...",
  "message": "Agent wallet set to tx-sender (SP1...) for agent 42.",
  "agentId": 42,
  "wallet": "SP1...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xmno..."
}

unset-wallet

Remove the agent wallet association from an agent identity. Caller must be the agent owner or an approved operator. Requires an unlocked wallet.

bun run identity/identity.ts unset-wallet --agent-id <id> [--fee <fee>] [--sponsored]

Options:

```
--agent-id
```
(required) — Agent ID to update (non-negative integer)
```
--fee
```
(optional) — Fee preset (
```
low
```
,
```
medium
```
,
```
high
```
) or micro-STX amount
```
--sponsored
```
(flag) — Submit as a sponsored transaction

Output:

json

{
  "success": true,
  "txid": "0xpqr...",
  "message": "Agent wallet cleared for agent 42.",
  "agentId": 42,
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xpqr..."
}

移除Agent身份与钱包的关联。调用者必须是Agent所有者或已授权的操作员。需要解锁的钱包。

bun run identity/identity.ts unset-wallet --agent-id <id> [--fee <fee>] [--sponsored]

选项：

```
--agent-id
```
（必填）——要更新的Agent ID（非负整数）
```
--fee
```
（可选）——费用预设（
```
low
```
、
```
medium
```
、
```
high
```
）或micro-STX金额
```
--sponsored
```
（标志）——作为赞助交易提交

输出：

json

{
  "success": true,
  "txid": "0xpqr...",
  "message": "Agent wallet cleared for agent 42.",
  "agentId": 42,
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xpqr..."
}

transfer

Transfer an agent identity NFT to a new owner. The active wallet (tx-sender) must equal the current owner. Transfer automatically clears the agent wallet association. Requires an unlocked wallet.

bun run identity/identity.ts transfer --agent-id <id> --recipient <address> [--fee <fee>] [--sponsored]

Options:

```
--agent-id
```
(required) — Agent ID (token ID) to transfer (non-negative integer)
```
--recipient
```
(required) — Stacks address of the new owner
```
--fee
```
(optional) — Fee preset (
```
low
```
,
```
medium
```
,
```
high
```
) or micro-STX amount
```
--sponsored
```
(flag) — Submit as a sponsored transaction

Output:

json

{
  "success": true,
  "txid": "0xstu...",
  "message": "Identity NFT transfer submitted for agent 42.",
  "agentId": 42,
  "sender": "SP1...",
  "recipient": "SP4...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xstu..."
}

将Agent身份NFT转移给新所有者。当前激活的钱包（交易发送者）必须是当前所有者。转移操作会自动清除Agent钱包关联。需要解锁的钱包。

bun run identity/identity.ts transfer --agent-id <id> --recipient <address> [--fee <fee>] [--sponsored]

选项：

```
--agent-id
```
（必填）——要转移的Agent ID（代币ID，非负整数）
```
--recipient
```
（必填）——新所有者的Stacks地址
```
--fee
```
（可选）——费用预设（
```
low
```
、
```
medium
```
、
```
high
```
）或micro-STX金额
```
--sponsored
```
（标志）——作为赞助交易提交

输出：

json

{
  "success": true,
  "txid": "0xstu...",
  "message": "Identity NFT transfer submitted for agent 42.",
  "agentId": 42,
  "sender": "SP1...",
  "recipient": "SP4...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xstu..."
}

get-metadata

Read a metadata value by key from the ERC-8004 identity registry. Returns the raw buffer value as a hex string. Does not require a wallet.

bun run identity/identity.ts get-metadata --agent-id <id> --key <key>

Options:

```
--agent-id
```
(required) — Agent ID to query (non-negative integer)
```
--key
```
(required) — Metadata key to read

Output:

json

{
  "success": true,
  "agentId": 42,
  "key": "name",
  "valueHex": "616c696365",
  "network": "mainnet"
}

从ERC-8004身份注册合约按键读取元数据值。返回原始缓冲区值的十六进制字符串。无需钱包即可使用。

bun run identity/identity.ts get-metadata --agent-id <id> --key <key>

选项：

```
--agent-id
```
（必填）——要查询的Agent ID（非负整数）
```
--key
```
（必填）——要读取的元数据键

输出：

json

{
  "success": true,
  "agentId": 42,
  "key": "name",
  "valueHex": "616c696365",
  "network": "mainnet"
}

get-last-id

Get the most recently minted agent ID from the ERC-8004 identity registry. Returns null if no agents have been registered. Does not require a wallet.

bun run identity/identity.ts get-last-id

Output:

json

{
  "success": true,
  "lastAgentId": 99,
  "network": "mainnet"
}

从ERC-8004身份注册合约获取最近铸造的Agent ID。如果尚未注册任何Agent，则返回null。无需钱包即可使用。

bun run identity/identity.ts get-last-id

输出：

json

{
  "success": true,
  "lastAgentId": 99,
  "network": "mainnet"
}

Notes

注意事项

Read operations (get, get-metadata, get-last-id) work without a wallet
Write operations require an unlocked wallet (
```
bun run wallet/wallet.ts unlock
```
)
Agent IDs are assigned by the contract upon registration — check the transaction result to find your assigned ID
Operator approvals allow a delegate address to update URI, metadata, and wallet for an agent
Transfer automatically clears the agent wallet association; use
```
set-wallet
```
after transfer if needed
The
```
agentWallet
```
key is reserved — use
```
set-wallet
```
/
```
unset-wallet
```
subcommands instead

读操作（get、get-metadata、get-last-id）无需钱包即可使用
写操作需要解锁钱包（
```
bun run wallet/wallet.ts unlock
```
）
Agent ID由合约在注册时分配——需查看交易结果获取分配的ID
操作员授权允许代理地址更新Agent的URI、元数据和钱包
转移操作会自动清除Agent钱包关联；如有需要，转移后使用
```
set-wallet
```
命令重新设置
```
agentWallet
```
键为保留键——请使用
```
set-wallet
```
/
```
unset-wallet
```
子命令替代