x402s

Free hey.eth for agents

Claim a free agent.hey.eth ENS for your agent.

State Channel Protocol Updates on X

/claim

Claim your hey.eth handle

/docs

Just use
curl -sS https://statechannel.org/heyeth/docs
to let your agent get its own, free ENS

SCP

Creates x402s for your agent wallet to accept 0 fee, instant payments

Overview

Agents need a simple, free, and reliable way to accept payments

The hey.eth API provides a clean path for agents to claim a human-readable handle, publish an ENS-style directory record, and resolve incoming payment addresses. The route set is small, explicit, and designed for automation-first use

Discover

Start with GET /heyeth/docs so an agent can discover the live route set without a browser flow.

Sign

Ask POST /heyeth/auth/challenge for the exact wallet-signing message tied to a handle and owner address.

Claim

Submit the signed nonce to POST /heyeth/claim to create or update the label.hey.eth directory record.

Handle Model

A clean agent handle becomes an ENS address.

Get a human-readable handle that maps to an Ethereum address/s, making it easy for agents to receive payments.

agent007.hey.eth

Directory Record

GET /heyeth/info/agent007
owner: 0x1234...7890
ETH: 0x1234...7890
USDC: 0x1234...7890

Human-readable naming, agent-first routing.

The page stays static, but the naming model is still expressive: readable handles for agents, a stable API surface for automation, and a CCIP path ready once the zone resolver is updated.

Free claims for open ENS-safe labels under hey.eth
Directory-style record with multiple addresses per handle
Explicit auth flow with signed nonces for secure claims and updates
CCIP gateway for addr() and basic text() lookups
SCP-based x402s payments for instant, gasless payments to agent wallets

Endpoints

The route set is small, explicit, and terminal-ready.

These are the routes an agent actually needs. No page state, no UI session, no embedded app logic.

DISCOVERY

GET /heyeth/docs

Returns docs JSON with branded endpoint URLs, example request bodies, zone status, and pay hub metadata.

LOOKUP

GET /heyeth/handle/:handle

Checks whether a label is claimed and returns the current owner, marker, address map, pay hub reference, and an x402s-style offers array for hub routing.

QUERY

GET /heyeth/handle?label=...

Supports query-style lookup too, so agents can call a stable path and pass the label as a query param.

GET /heyeth/info/:handle

Returns the claimed handle record directly, including the owner and published addresses.

UPDATE

PUT /heyeth/handle/:handle

Updates a claimed handle with a fresh signed nonce from the same owner wallet. This is the explicit later-edit route.

AUTH

POST /heyeth/auth/challenge

Returns the exact EIP-191 personal_sign / signMessage payload for a handle and owner wallet before a claim or update.

CLAIM

POST /heyeth/claim

Reserves an available label and writes default ETH and USDC records for the supplied owner address. Same-owner updates still work here for backward compatibility, but PUT /heyeth/handle/:handle is the cleaner edit path.

CCIP

POST /heyeth/ccip

Serves signed gateway responses for resolver calls like addr() under *.hey.eth.

SCP

State Channel Protocol

hey.eth handles are also x402s-compatible agent wallets, so you can send them instant, gasless payments via SCP with no on-chain fees or approvals. Just resolve the handle to get the current owner address and send to the hub's x402s.

Examples

Start in your terminal with simple HTTP.

No frontend session, just requests.

The goal is fast automation. Discover the route set, check a label, request a signing challenge, sign the exact challenge message with the owner wallet, submit the signed claim, and hit the CCIP gateway without ever touching browser UI.

claim.sh
# jq + cast example: sign challenge.message with EIP-191 personal_sign
OWNER=0x1234567890123456789012345678901234567890
OWNER_PK=0xyour_private_key_here
HANDLE=agent007

CHALLENGE=$(curl -sS https://statechannel.org/heyeth/auth/challenge \
  -H 'content-type: application/json' \
  --data "{
    \"handle\": \"$HANDLE\",
    \"owner\": \"$OWNER\"
  }")

MESSAGE=$(printf '%s' "$CHALLENGE" | jq -r '.challenge.message')
NONCE=$(printf '%s' "$CHALLENGE" | jq -r '.challenge.nonce')

# sign the exact returned string with personal_sign / signMessage
# do not hash it yourself and do not hex-encode it first
SIGNATURE=$(cast wallet sign --private-key "$OWNER_PK" "$MESSAGE")

# if you use a wallet UI instead, sign challenge.message exactly as returned
curl -sS https://statechannel.org/heyeth/claim \
  -H 'content-type: application/json' \
  --data "{
    \"handle\": \"$HANDLE\",
    \"owner\": \"$OWNER\",
    \"nonce\": \"$NONCE\",
    \"signature\": \"$SIGNATURE\",
    \"addresses\": {
      \"ETH\": \"$OWNER\",
      \"BTC\": \"bc1qexample...\"
    }
  }"

claim.mjs
# ethers example: sign the exact challenge.message with wallet.signMessage()
import { Wallet } from "ethers";

const wallet = new Wallet("0xyour_private_key_here");
const handle = "agent007";

const challengeResp = await fetch("https://statechannel.org/heyeth/auth/challenge", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    handle,
    owner: wallet.address
  })
});

const { challenge } = await challengeResp.json();

# EIP-191 personal_sign style signature over the exact returned string
const signature = await wallet.signMessage(challenge.message);

const claimResp = await fetch("https://statechannel.org/heyeth/claim", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    handle,
    owner: wallet.address,
    nonce: challenge.nonce,
    signature,
    addresses: {
      ETH: wallet.address
    },
    texts: {
      "com.twitter": "agent007"
    }
  })
});

console.log(await claimResp.json());

update.sh
# later edits use a fresh challenge + signature from the same owner wallet
OWNER=0x1234567890123456789012345678901234567890
OWNER_PK=0xyour_private_key_here
HANDLE=agent007

CHALLENGE=$(curl -sS https://statechannel.org/heyeth/auth/challenge \
  -H 'content-type: application/json' \
  --data "{
    \"handle\": \"$HANDLE\",
    \"owner\": \"$OWNER\"
  }")

MESSAGE=$(printf '%s' "$CHALLENGE" | jq -r '.challenge.message')
NONCE=$(printf '%s' "$CHALLENGE" | jq -r '.challenge.nonce')
SIGNATURE=$(cast wallet sign --private-key "$OWNER_PK" "$MESSAGE")

curl -sS -X PUT https://statechannel.org/heyeth/handle/$HANDLE \
  -H 'content-type: application/json' \
  --data "{
    \"owner\": \"$OWNER\",
    \"nonce\": \"$NONCE\",
    \"signature\": \"$SIGNATURE\",
    \"addresses\": {
      \"BTC\": \"bc1qupdated...\"
    }
  }"

lookup.sh
# inspect a label
curl -sS https://statechannel.org/heyeth/handle/agent007

# or query the stable handle endpoint
curl -sS 'https://statechannel.org/heyeth/handle?label=agent007'

# inspect live resolver status
curl -sS https://statechannel.org/heyeth/status

# inspect Sepolia pay.eth metadata
curl -sS https://statechannel.org/heyeth/pay/sepolia

ccip.sh
# send a CCIP gateway request
curl -sS https://statechannel.org/heyeth/ccip \
  -H 'content-type: application/json' \
  --data '{
    "sender": "0xResolverAddress",
    "data": "0x..."
  }'

State Channel Protocol

hey.eth is more than an ENS, it's also an x402s-compatible agent wallet.

hey.eth handles are designed to work seamlessly with the State Channel Protocol, enabling instant, gasless payments to agent wallets. By resolving a hey.eth handle, you can retrieve the current owner address and send payments directly to the hub's x402s, making it an ideal solution for agents looking to receive payments without on-chain fees or approvals.

Current public references: GET /heyeth/status and GET /heyeth/pay/sepolia

Get your agent a hey.eth

$ curl -sS https://statechannel.org/heyeth/docs

Docs JSON Check Example Browser Wallet