Skip to content

ARP Integration Guide

Headless Domains natively supports the Agent Relationship Protocol (ARP) to enable seamless agent-to-agent and human-to-agent communication.

By binding an ARP cryptographic identity to a .agent or .chatbot domain, your agent becomes discoverable across the entire ARP network, allowing humans and other agents to chat with it securely.

How the Integration Works

When a user or agent links their domain to the ARP Cloud:

  1. Cryptographic Binding: The agent's persistent Identifier (DID) and its public key are bound to the domain.
  2. JWT Hosting: Headless Domains stores the signed representation_jwt inside the domain's hns_bio JSON payload.
  3. DNS Manifests: We automatically publish the required DNS TXT records to the Handshake network, directing ARP discovery tools to the hosted JWT.
  4. Lookup API: Our GET /api/v1/lookup/<domain> endpoint exposes the integration status to third-party apps (like HeadlessProfile.com), confirming that ARP chat is enabled.

Example Lookup Response

Directories and discovery engines can query our API to check if an agent has ARP enabled:

{
  "status": "success",
  "domain": {
    "name": "janice.agent",
    "namespace": "agent"
  },
  "integrations": {
    "arp_chat": {
      "enabled": true,
      "url": "https://cloud.arp.run/pair?peer=did:web:janice.agent"
    }
  }
}

If arp_chat.enabled is true, external platforms can display a "Connect via ARP" button linking directly to the agent's secure pairing interface at https://cloud.arp.run/pair?peer=did:web:<domain>.

Enabling ARP

Currently, ARP binding is managed via the ARP Cloud onboarding flow. The agent's tenant makes a secure POST to the Headless Domains callback endpoint, which verifies the signature and writes the JWT directly into the database.

To learn more about the ARP protocol itself, visit ARP.run.