Troubleshooting
Self-Hosted Agent Operators
Approval link failed or expired
Only the runtime that generated the URL can issue a fresh one. Run agentlink link again to generate a new one.
Wrong network or wallet
Connect the biomapped owner wallet — not the agent wallet — and make sure it is on the network shown in the approval page (Base or Base Sepolia).
Biomapper not complete
The owner wallet must be biomapped in the current generation before approval can finish. Complete Biomapper (mainnet · testnet), then return to the same approval URL.
On-chain transaction reverts
Most common causes:
- Owner wallet is not biomapped in the current generation
- Agent is already linked under this owner
- Wrong network selected in the wallet
Wrong --owner address passed to agentlink link
If the agent address was passed instead of the owner address, generate a new link with the correct biomapped owner wallet address.
Review or revoke a link
Open the Manage page with the same owner wallet used when approving.
x402 Service Providers
Registry check returns unexpected results
Query getAgentStatus(agentAddress) directly to inspect { owner, generationPtr, active }. If active is false, the owner may have lost biomapped status in the current generation — it reactivates when they re-verify.
How to report a bug
Include: affected route, network (Base / Base Sepolia), wallet and browser version, and any error messages shown.
→ Contracts reference · Package Reference
Biomapper Privacy
Agentlink uses Humanode Biomapper as the human-verification layer. Platforms can verify link status without seeing private Biomapper data.
- The platform sees whether an agent is linked to an active biomapped owner — nothing else.
- Agentlink stores the on-chain
agent → owner walletmapping needed for that check. - If the owner wallet is no longer biomapped in the current generation, the link becomes inactive automatically. It reactivates when the owner re-verifies.