Handles

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

Claim a handle

PUT /parties/me/handle sets your handle. Send the bare name (acme), not @acme. The fastest path is the dashboard, under Settings → Profile.

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 setHandle --handle acme

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

Agent handles

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.

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 a procurement agent named "Procurement Agent" with the handle slug procurementagent.

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" } } }'

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 with POST /payments and a handle counterparty. The handle resolves to an existing party, so funds route straight to their wallet with no claim link. The leading @ is optional. See Send a payment for the full payment mechanics and every counterparty type.

import uuid
from naturalpay import Natural

agent_client = Natural(
    x_agent_id="agt_019cd1798d637a4da75dce386343931d",
    x_instance_id=str(uuid.uuid4()),
)

payment = agent_client.payments.create(
    amount=500_000,
    currency="USD",
    counterparty={"type": "handle", "value": "@natural-contractor"},
    description="Q4 development work",
    idempotency_key=str(uuid.uuid4()),
)
print(payment.data.id)

const payment = await client.payments.create(
  {
    amount: 500_000,
    currency: "USD",
    counterparty: { type: "handle", value: "@natural-contractor" },
    description: "Q4 development work",
    idempotencyKey: crypto.randomUUID(),
  },
  {
    xAgentId: "agt_019cd1798d637a4da75dce386343931d",
    xInstanceId: crypto.randomUUID(),
  },
);
console.log(payment.data.id);

natural payments create \
  --amount 500000 \
  --currency USD \
  --params '{"counterparty": {"type": "handle", "value": "@natural-contractor"}}' \
  --description "Q4 development work" \
  --x-agent-id agt_019cd1798d637a4da75dce386343931d \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Using my Procurement Agent, pay @natural-contractor $5,000 for Q4 development work.

curl -X POST https://api.natural.com/payments \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Agent-ID: agt_019cd1798d637a4da75dce386343931d" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "amount": 500000,
        "currency": "USD",
        "counterparty": { "type": "handle", "value": "@natural-contractor" },
        "description": "Q4 development work"
      }
    }
  }'

Request by handle

Collect from someone at their @handle with POST /payment-requests and a handle payer. Because the handle resolves to a known party, Natural notifies them in their dashboard instead of sending a claim link. See Request a payment to track the request or cancel it.

import uuid
from naturalpay import Natural

agent_client = Natural(
    x_agent_id="agt_019cd1798d637a4da75dce386343931d",
    x_instance_id=str(uuid.uuid4()),
)

request = agent_client.payment_requests.create(
    amount=2500,
    currency="USD",
    description="Invoice 7",
    payer_name="Natural Client",
    payer={"type": "handle", "value": "@natural-client"},
    idempotency_key=str(uuid.uuid4()),
)
print(request.data.id)

const request = await client.paymentRequests.create(
  {
    amount: 2500,
    currency: "USD",
    description: "Invoice 7",
    payerName: "Natural Client",
    payer: { type: "handle", value: "@natural-client" },
    idempotencyKey: crypto.randomUUID(),
  },
  {
    xAgentId: "agt_019cd1798d637a4da75dce386343931d",
    xInstanceId: crypto.randomUUID(),
  },
);
console.log(request.data.id);

natural payment-requests create \
  --amount 2500 \
  --currency USD \
  --description "Invoice 7" \
  --payer-name "Natural Client" \
  --params '{"payer": {"type": "handle", "value": "@natural-client"}}' \
  --x-agent-id agt_019cd1798d637a4da75dce386343931d \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Using my Procurement Agent, request $25 from @natural-client for Invoice 7.

curl -X POST https://api.natural.com/payment-requests \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Agent-ID: agt_019cd1798d637a4da75dce386343931d" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "amount": 2500,
        "currency": "USD",
        "description": "Invoice 7",
        "payerName": "Natural Client",
        "payer": { "type": "handle", "value": "@natural-client" }
      }
    }
  }'

Overview

Common use cases

Products

Guides

Claim a handle

Agent handles

Pay by handle

Request by handle

​Claim a handle

​Agent handles

​Pay by handle

​Request by handle

Claim a handle

Agent handles

Pay by handle

Request by handle