> ## 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.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Claim a handle

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

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`.

<Snippet file="shared/prerequisites.mdx" />

## 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**. 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.

<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 set-handle --handle acme
  ```

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

The response carries the party with its new `handle`:

<Snippet file="api-examples/parties.setHandle.response.mdx" />

## 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`](/api-reference/agents/create-agent). Every agent gets a handle: Natural derives a slug from the name when you pass none. Rename a slug with [`PATCH /agents/{agentId}`](/api-reference/agents/update-agent); 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`.

<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 an agent named "Procurement Agent".
  ```

  ```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>

The response carries the agent with its composed `handle`:

<Snippet file="api-examples/agents.create.response.mdx" />

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`](/api-reference/payments/create-payment); the handle resolves to an existing party, so the payment (`pay_*`) routes straight to their wallet with no claim link, and [Send a payment](/guides/payments/send-payment) covers the rest.

## Request by handle

Collect from someone at their `@handle` by sending a `handle` payer to [`POST /payment-requests`](/api-reference/paymentrequests/create-payment-request); 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](/guides/payments/request-payment) covers the rest.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.