Skip to main content
LearnGuidesVerify agent identity
GUIDE

Earn the GitHub and domain verification badges.

8 minutes
SHORT ANSWER

Start a verification flow via the API, complete the proof (GitHub OAuth handshake or a DNS TXT record), then confirm by polling. Each method earns a badge that appears on the agent's public profile. Badges re-check monthly. Counterparties hover the badge to see who verified what and when, which is the trust signal serious payers look for.

PREREQUISITES

Before you start.

  • An existing agent profile and API key (see the add-payments-to-agent guide).
  • For the GitHub badge: ability to authorize the Blockchain0x app on the GitHub org or user that the agent represents.
  • For the domain badge: control over DNS for the apex domain you want to verify (or whichever host your DNS provider supports for TXT records).
  • 10 minutes wallclock for DNS verification (most propagate in under a minute, but allow up to 10).
  • Familiarity with the agent payment identity concept - badges are one of its layers.
STEP 1 OF 3

Start a GitHub verification.

The GitHub badge proves that the agent is associated with a specific GitHub user or org. Call startVerification with method "github" and the org or user handle. The API returns an OAuth URL; the human admin who actually owns the GitHub identity opens it and grants the Blockchain0x app read access to public profile information.

TypeScript
import { Blockchain0x } from "@blockchain0x/sdk";

const client = new Blockchain0x({ apiKey: process.env.BLOCKCHAIN0X_API_KEY! });

const flow = await client.agents.startVerification("agt_01J9QKE...", {
  method: "github",
  github_org_or_user: "your-org",
});

// Open this URL in a browser to complete the OAuth handshake.
console.log(flow.auth_url);
console.log(flow.flow_id);
Python
from blockchain0x import Client
import os

client = Client(api_key=os.environ["BLOCKCHAIN0X_API_KEY"])

flow = client.agents.start_verification(
    "agt_01J9QKE...",
    method="github",
    github_org_or_user="your-org",
)

print(flow.auth_url)
print(flow.flow_id)

Once the OAuth grant lands, the verification flips to 'verified' on the next poll. The badge appears on the agent's public page within a minute or two.

STEP 2 OF 3

Start a domain verification.

The domain badge proves control over a registered DNS domain. Call startVerification with method "domain". The API returns a TXT record value that you publish in your DNS. After propagation, the API observes the record and flips the badge to verified.

TypeScript
const flow = await client.agents.startVerification("agt_01J9QKE...", {
  method: "domain",
  domain: "yourcompany.com",
});

// flow.expected_txt_value is what you publish in DNS.
console.log(flow.expected_txt_record);
// e.g. "blockchain0x-verify=v01j9r6y...abc"
Python
flow = client.agents.start_verification(
    "agt_01J9QKE...",
    method="domain",
    domain="yourcompany.com",
)

# flow.expected_txt_value is what you publish in DNS.
print(flow.expected_txt_record)
# e.g. "blockchain0x-verify=v01j9r6y...abc"

Publish the returned value as a TXT record:

# Add this TXT record at the apex of your domain
# (or at _blockchain0x.<domain> if your DNS host requires a subdomain).

Type:    TXT
Name:    @          (or yourcompany.com)
Value:   blockchain0x-verify=v01j9r6y...abc
TTL:     300        (5 minutes is fine)
STEP 3 OF 3

Confirm the badge is live.

Poll checkVerification until the state is "verified". For GitHub this typically happens within a minute of the OAuth grant; for domain it depends on DNS propagation but usually completes within 10 minutes.

TypeScript
// After the OAuth callback (GitHub) or DNS propagation (domain),
// poll to confirm. The flow_id is what the API returned earlier.
const status = await client.agents.checkVerification(flow.flow_id);

if (status.state === "verified") {
  console.log("Badge earned:", status.method);
  // status.next_recheck_at tells you when the monthly re-check fires.
}
Python
status = client.agents.check_verification(flow.flow_id)

if status.state == "verified":
    print("Badge earned:", status.method)
    # status.next_recheck_at tells you when the monthly re-check fires.

After verification, the agent's public page (wallet.blockchain0x.com/a/<slug>) shows the badge alongside the agent's other identity claims. Hovering the badge reveals which method earned it, when, and when the next re-check is scheduled. That hover popover is what counterparties read before approving a payment or allowlisting your wallet.

COMMON PITFALLS

Four mistakes that delay or break verification.

Verifying the wrong GitHub identity

If you use your personal GitHub account for the OAuth handshake but the agent represents an organization, the badge will say 'verified by @yourhandle' rather than 'verified by yourcompany'. Counterparties expecting the org will look skeptical at the personal-handle badge. Use a GitHub account that matches the agent's claimed identity, and prefer org-level verification over user-level whenever possible.

DNS TXT records published at the wrong host

Some DNS hosts accept the TXT record at the apex (just '@'), others require a subdomain (typically '_blockchain0x'). If your verification stays in 'pending' after 30 minutes, the record is almost always at the wrong location. The flow response includes both the expected location and the expected value - double-check both, and verify externally with 'dig TXT yourdomain.com' before assuming the API is at fault.

Forgetting that verification expires

Verification badges re-check monthly. If your DNS TXT record gets removed during a host migration, or if you remove the agent's OAuth grant on GitHub, the next re-check fails and the badge is removed automatically. Counterparties notice. Keep the verification artifacts in place as part of your standing infrastructure, and treat their accidental removal as an outage.

Showing the badge but not building trust around it

Badges are necessary but not sufficient. A counterparty looking at your agent's public page will weight the badge alongside recent transaction history, the agent's reason-for-payment patterns, and any social proof in your wider product. Treat the badge as the floor - earning it makes you eligible for serious counterparties, but it does not by itself make them trust you. Build the rest of the trust signals around it.

NEXT STEPS

After the badges are in place.

With identity verified, finish the production hardening checklist: a security review of the wallet itself, spend controls if the agent pays out, and the standard webhook patterns so payments do not slip through during operational hiccups.

Secure your agent wallet before going live

15 minutes

Set up agent spend controls that survive prompt injection

8 minutes

The webhook patterns developers ask about most

15 minutes

Full reference at docs.blockchain0x.com. Product surface: Agent identity.

Last reviewed: 2026-05-15. Published under CC BY 4.0.

Earn the trust the badges signal.

GitHub, domain, email verifications. Eight minutes to set up. Free.