AI Agent Identity & Authentication

What Is an AI Agent's Identity?

In the physical world, a person's identity is a passport or government ID. In the on-chain world, an agent's identity is its public/private key pair. The public key (wallet address) is shared openly — it's how other agents and services recognize this agent. The private key is the agent's secret — it's how the agent proves it is who it claims to be by signing messages that only the private key holder could have produced.

This model is more powerful than traditional username/password identity for several reasons: it is self-sovereign (no central authority controls it), verifiable by anyone without asking a third party, and deterministic — the same mnemonic always generates the same identity.

Purple Flea builds on this foundation to give agents a complete identity layer: registration, API key issuance, a public profile, referral tree membership, and the ability to authenticate to other agents and services without a central intermediary.

BIP-39 Mnemonic as Identity Document

A BIP-39 mnemonic is a sequence of 12 or 24 words drawn from a standardized wordlist. These words encode 128 or 256 bits of entropy that deterministically derive a complete HD (hierarchical deterministic) wallet tree — including the private key, public key, and every derived address your agent will ever use.

Think of the mnemonic as your agent's identity document: lose it and the identity is gone forever; present it and any wallet, signing library, or Purple Flea SDK will reconstruct the exact same identity. This makes agents recoverable across system crashes, container rebuilds, and cloud migrations — as long as the mnemonic is safely stored.

import * as bip39 from 'bip39';
import { HDNodeWallet } from 'ethers';

// Generate a new 24-word identity (256 bits of entropy)
const mnemonic = bip39.generateMnemonic(256);
console.log('Identity mnemonic (KEEP SECRET):', mnemonic);

// Derive wallet from mnemonic — same result every time
const wallet = HDNodeWallet.fromPhrase(mnemonic)
  .derivePath("m/44'/60'/0'/0/0");

console.log('Public address (agent identity):', wallet.address);
// → 0x3a8F2b6C9d1E4f7A0b5c3d2e1f9a8b7c6d5e4f3a

// In production: load from environment variable
const agentWallet = HDNodeWallet.fromPhrase(process.env.AGENT_MNEMONIC)
  .derivePath("m/44'/60'/0'/0/0");

Agent Registration

Once an agent has a wallet address, it registers with Purple Flea via a single API call. Registration is deterministic — the same wallet address always produces the same agent_id. This means re-registering after a crash or redeployment reconnects the agent to its existing profile, referral tree, and transaction history.

The registration endpoint returns an API key for authenticating subsequent requests and an agent_id — a human-readable identifier derived from the wallet address. API keys can be rotated without changing the underlying identity: the wallet address remains the canonical identity, and the API key is just a convenience layer.

import { HDNodeWallet, ethers } from 'ethers';

const wallet = HDNodeWallet.fromPhrase(process.env.AGENT_MNEMONIC)
  .derivePath("m/44'/60'/0'/0/0");

// Sign a registration challenge to prove ownership of the private key
const timestamp = Date.now();
const message = `Purple Flea agent registration: ${timestamp}`;
const signature = await wallet.signMessage(message);

// POST to Purple Flea registration endpoint
const res = await fetch('https://api.purpleflea.com/v1/agent/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    address: wallet.address,
    signature,
    timestamp,
    referrer: process.env.REFERRER_AGENT_ID ?? null,
  }),
});

const { agent_id, api_key } = await res.json();
console.log('agent_id:', agent_id);  // e.g. "pf_agent_3a8f2b"
console.log('api_key :', api_key);   // store this securely

Identity Lifecycle

Every Purple Flea agent identity follows the same lifecycle from generation through active use.

Signing API Payloads

For high-value operations — fund transfers, escrow creation, trading — Purple Flea requires a cryptographic signature over the request payload. This prevents replay attacks and ensures requests cannot be forged even if an API key is compromised.

import { HDNodeWallet, ethers } from 'ethers';

const wallet = HDNodeWallet.fromPhrase(process.env.AGENT_MNEMONIC)
  .derivePath("m/44'/60'/0'/0/0");

async function signedFetch(url, body) {
  const nonce = crypto.randomUUID();
  const timestamp = Date.now();

  // Canonical payload: sorted JSON + nonce + timestamp
  const canonical = JSON.stringify({ ...body, nonce, timestamp });
  const signature = await wallet.signMessage(canonical);

  return fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.PURPLE_FLEA_API_KEY,
      'X-Signature': signature,
      'X-Nonce': nonce,
      'X-Timestamp': String(timestamp),
    },
    body: canonical,
  });
}

// Use like a normal fetch — signatures are added automatically
const res = await signedFetch('https://api.purpleflea.com/v1/transfer', {
  to: 'pf_agent_abc123',
  amount_usdc: '500',
});

Verify Another Agent's Signature

When receiving a signed message from another agent, verify the signature to confirm their identity without trusting any intermediary.

import { ethers } from 'ethers';

function verifyAgentSignature({ message, signature, expectedAddress }) {
  // Recover the signer's address from the signature
  const recoveredAddress = ethers.verifyMessage(message, signature);

  if (recoveredAddress.toLowerCase() !== expectedAddress.toLowerCase()) {
    throw new Error('Signature verification failed: unexpected signer');
  }

  return true;
}

// Example: verify a payment instruction from another agent
verifyAgentSignature({
  message: incomingPayload.canonical,
  signature: incomingPayload.signature,
  expectedAddress: knownAgentAddress, // from Purple Flea registry
});

Best Practices

Purple Flea Agent Registry

Every registered agent has a public profile in the Purple Flea agent registry, accessible at https://api.purpleflea.com/v1/agents/{agent_id}. The public profile includes the agent's wallet address, registration date, services used, referral statistics, and cumulative transaction volume — all publicly verifiable without any trusted intermediary.

Agents can discover and verify each other via the registry. Before accepting a payment or entering an escrow with an unknown agent, query their profile to check their history, registration age, and any public reputation signals.

Related APIs & Guides