> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handles

> Claim a @handle to give you and your agents and identity

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`](/api-reference/parties/set-party-handle) sets your handle. Send the bare name (`acme`), not `@acme`. The fastest path is the dashboard, under **Settings → Profile**.

<CodeGroup>
  ```python Python theme={null}
  party = client.parties.set_handle(handle="acme")
  print(party.data.attributes.handle)
  ```

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

  ```bash CLI theme={null}
  natural parties setHandle --handle acme
  ```

  ```bash cURL theme={null}
  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" } } }'
  ```
</CodeGroup>

## 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`](/api-reference/agents/create-agent).

<CodeGroup>
  ```python Python theme={null}
  import uuid

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

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

  ```bash CLI theme={null}
  natural agents create --name "Procurement Agent" --slug procurementagent --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Create a procurement agent named "Procurement Agent" with the handle slug procurementagent.
  ```

  ```bash cURL theme={null}
  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" } } }'
  ```
</CodeGroup>

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`](/api-reference/payments/create-payment) 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](/guides/payments/send-payment) for the full payment mechanics and every counterparty type.

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```

  ```bash CLI theme={null}
  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)"
  ```

  ```text MCP theme={null}
  Using my Procurement Agent, pay @natural-contractor $5,000 for Q4 development work.
  ```

  ```bash cURL theme={null}
  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"
        }
      }
    }'
  ```
</CodeGroup>

## Request by handle

Collect from someone at their `@handle` with [`POST /payment-requests`](/api-reference/paymentrequests/create-payment-request) 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](/guides/payments/request-payment) to track the request or cancel it.

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```

  ```bash CLI theme={null}
  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)"
  ```

  ```text MCP theme={null}
  Using my Procurement Agent, request $25 from @natural-client for Invoice 7.
  ```

  ```bash cURL theme={null}
  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" }
        }
      }
    }'
  ```
</CodeGroup>

<Snippet file="shared/webhook-payment-request-fulfill.mdx" />