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

# Agent turn

> Send the Pesarc agent a plain-language message; it understands and acts in one turn.

Runs one turn of the Pesarc agent. Give it a plain-language request and it
understands and acts — create a market, pay a bill, or submit and settle a
cross-border transfer peer-to-peer in local currency — then replies with what it
did. This is the same brain behind the in-app chat and the WhatsApp bridge.

## Request

<ParamField header="Authorization" type="string" required>
  `Bearer sk_live_…`
</ParamField>

<ParamField body="message" type="string" required>
  The user's request, 1–500 characters. Pass it verbatim, e.g.
  `"Send ₦50,000 to Ama in Accra"`.
</ParamField>

## Response

The body carries the agent's `reply` and any action details for the turn. The
HTTP status reflects the turn outcome; on a bad request the agent still returns a
human-readable `reply`.

<RequestExample>
  ```bash cURL theme={null}
  curl https://pesarc.xyz/api/agent/settle \
    -H "Authorization: Bearer sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{ "message": "Pay my Ikeja electricity bill" }'
  ```

  ```ts TypeScript theme={null}
  const res = await fetch("https://pesarc.xyz/api/agent/settle", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PESARC_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "Send ₦50,000 to Ama in Accra" }),
  });
  const result = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "reply": "Sent ₦50,000 to Ama. She receives ₵470, settling now.",
    "action": "transfer"
  }
  ```

  ```json 400 theme={null}
  { "ok": false, "reply": "Say what you'd like to send." }
  ```
</ResponseExample>

<Warning>
  This endpoint moves money. In your own product, show the agent's described action
  to the user and get explicit confirmation before treating it as authorised, and
  keep the call server-side so your key is never exposed. The endpoint is
  rate-limited — retry with backoff.
</Warning>

<Note>
  The exact response fields depend on the action the agent takes (transfer, bill,
  market, or an informational answer). Always render `reply` to the user, and
  branch on the action fields you care about.
</Note>