Claim a handle

Claim @acme and anyone on Natural can interact with your party (pty_*) by name. Each agent (agt_*) gets its own handle under your party, for example @acme-procurementagent.

PUT /parties/me/handle sets your handle. Send the bare name (acme), not @acme. The fastest path is the dashboard, under Settings → Profile. Set it from the dashboard or with your API key; agent keys cannot change handles. A handle is 3 to 30 lowercase letters, digits, dots, or underscores. You can rename it but never clear it, and the old name stays reserved for you for 14 days.

party = client.parties.set_handle(handle="acme")
print(party.data.attributes.handle)

const party = await client.parties.setHandle({ handle: "acme" });
console.log(party.data.attributes.handle);

natural parties set-handle --handle acme

curl -X PUT https://api.natural.com/parties/me/handle \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "attributes": { "handle": "acme" } } }'

The response carries the party with its new handle:

Give an agent a handle

Each agent gets its own handle: its handle composes with your party handle as @party-agent. Set the handle when you create the agent, on POST /agents. Every agent gets a handle: Natural derives a slug from the name when you pass none. Rename a slug with PATCH /agents/{agentId}; it can never be cleared. Claim a slug from the dashboard or with your API key; an agent key request that carries slug is refused with handle_human_session_required.

import uuid

agent = client.agents.create(
    name="Procurement Agent",
    slug="procurementagent",
    idempotency_key=str(uuid.uuid4()),
)
print(agent.data.id)

const agent = await client.agents.create({
  name: "Procurement Agent",
  slug: "procurementagent",
  idempotencyKey: crypto.randomUUID(),
});
console.log(agent.data.id);

natural agents create --name "Procurement Agent" --slug procurementagent --idempotency-key "$(uuidgen)"

Create an agent named "Procurement Agent".

curl -X POST https://api.natural.com/agents \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "data": { "attributes": { "name": "Procurement Agent", "slug": "procurementagent" } } }'

The response carries the agent with its composed handle: Once your party has a handle and the agent has a slug, others pay or request that agent directly at @acme-procurementagent.

Pay by handle

Pay someone at their @handle by sending a handle counterparty to POST /payments; the handle resolves to an existing party, so the payment (pay_*) routes straight to their wallet with no claim link, and Send a payment covers the rest.

Request by handle

Collect from someone at their @handle by sending a handle payer to POST /payment-requests; the handle resolves to an existing party, so they get a payment link into their dashboard rather than a claim link, and Request a payment covers the rest.

Overview

Common use cases

Products

Guides

Claim a handle

Claim a handle

Give an agent a handle

Pay by handle

Request by handle

​Claim a handle

​Give an agent a handle

​Pay by handle

​Request by handle

Claim a handle

Give an agent a handle

Pay by handle

Request by handle