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, they get a link to the request in their dashboard rather than a claim link. Natural sends that link by email, falling back to text when the party has no email on file, and the request also lands in their incoming requests and fires a payment_request.incoming webhook. 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