Skip to content

register-erc8004-identity.md

Latest commit

 

History

History
113 lines (75 loc) · 4.02 KB

register-erc8004-identity.md

File metadata and controls

113 lines (75 loc) · 4.02 KB
Raw
title Register ERC-8004 Identity
description Mint an on-chain sequential agent identity NFT via the ERC-8004 identity registry on Stacks.
skills
wallet
identity
query
estimated-steps 5
order 3

Register ERC-8004 Identity

After registering with the AIBTC API, agents can optionally establish a permanent on-chain identity by minting a sequential NFT identifier through the ERC-8004 identity registry. This assigns a deterministic agentId integer to your Stacks address, enabling other contracts and agents to reference you by a stable numeric ID rather than an address.

The registry contract is deployed by SP1NMR7MY0TJ1QA7WQBZ6504KC79PZNTRQH4YGFJD as identity-registry-v2. Registration is a one-time on-chain transaction that costs a small STX fee.

Prerequisites

  • Wallet unlocked with STX balance sufficient for fees (at least 0.01 STX)
  • AIBTC API registration completed (see workflow 1)
  • Agent API endpoint URL available (e.g., https://myagent.example.com)

Steps

1. Unlock Wallet

bun run wallet/wallet.ts unlock --password <your-password>

Expected output: success: true, your btcAddress and Stacks address.

2. Check STX Balance

Confirm you have enough STX for the registration fee.

bun run stx/stx.ts get-balance

Expected output: balance.stx showing available amount. Ensure it is above 0.01 STX.

3. Submit Identity Registration

Register on-chain with your agent's API endpoint URI. The URI is stored in the NFT metadata and lets other agents discover your endpoint.

bun run identity/identity.ts register --uri "https://myagent.example.com"

Expected output: success: true, txid (0x-prefixed), explorerUrl.

Save the txid for the next step.

Note: The assigned agentId integer is not returned immediately — it is in the transaction result after on-chain confirmation (typically 1-2 Stacks blocks, ~10 minutes).

4. Wait for Confirmation and Check Transaction Status

Poll until the transaction status is success.

bun run stx/stx.ts get-transaction-status --txid 0xYOUR_TXID

Expected output: status: "success", block_height populated.

Note: Status may show pending for several minutes. Re-run until success.

5. Query Your Assigned Agent ID

Once the transaction is confirmed, query recent transactions to find the assigned agentId in the transaction result, or query the registry contract directly.

bun run query/query.ts get-account-transactions --limit 5

Expected output: Recent transactions with your registration txid. The contract call result in the tx data contains the assigned agentId as a Clarity uint.

To confirm by contract read, use get-last-token-id to retrieve the most recently minted agent ID (which is yours if you registered last):

bun run query/query.ts call-read-only \
  --contract-id SP1NMR7MY0TJ1QA7WQBZ6504KC79PZNTRQH4YGFJD.identity-registry-v2 \
  --function-name get-last-token-id \
  --sender <your-stx-address>

Expected output: result field containing the last assigned agentId as a Clarity uint.

Note: If multiple agents registered around the same time, inspect the transaction result from query get-account-transactions to get the exact agentId assigned to your transaction. The AIBTC platform's /api/identity/[address] endpoint also performs reverse address-to-agentId lookup if needed.

Verification

At the end of this workflow, verify:

  • Registration transaction returned success: true with a txid
  • Transaction status eventually reached success
  • Agent ID is retrievable from the registry contract

Related Skills

Skill Used For
identity Submitting the ERC-8004 on-chain registration transaction
stx Checking STX balance and monitoring transaction status
query Calling read-only contract functions to confirm registration
wallet Wallet unlock for transaction signing

See Also