Skip to main content
POST
Draft payment proposals from a conversation (ALPHA)

Authorizations

x-api-key
string
header
required

Path Parameters

payment_agent_id
string
required

Body

application/json

A freeform proposals conversation. The server is stateless — send the whole history in messages on each call. prompt is a convenience for a single-shot turn (or the latest user message); it is appended after messages. At least one of prompt or messages must be non-empty. Supplying both is valid only when messages does not already end with a user turn; otherwise the request is rejected with 400 (two consecutive user turns are not allowed).

prompt
string

Single-shot input, appended as the latest user turn.

messages
object[]

The conversation so far, oldest first.

developer_fee
object

Your developer fee, declared per payout type. A conversion is charged the rate for the kind of payout it funds: swap_bps for a crypto payout, offramp_bps for a bank payout. Omit a rate, or send zero, and that payout type carries no fee at all — nothing is charged, nothing is added to the amount, and the agent is told nothing about a fee it could mention. The two are independent, so one conversation can charge a swap and stay silent about a bank payout in the same turn.

Both rates are DEFAULTS for the auto-accounts a request creates. An action-level fee_bps is an explicit override and still wins outright, for either type.

timezone
string

The customer's IANA timezone (e.g. "America/Los_Angeles"). When present, the agent resolves every relative date ("tomorrow", "Friday") and clock time ("10 am") in THIS timezone; a date without a time is drafted for the first working hours of the local day (10:00) and the draft summary states the resolved local time; a time without a date means its next local occurrence. Absent or unrecognized ⇒ times resolve as UTC and the agent says so when a specific clock time matters. Send it on EVERY turn — the server is stateless. Note: the zone's UTC offset is captured at drafting time, so a DST transition before a far-future fire date shifts the fire time by the DST delta.

Maximum string length: 64
Example:

"America/Los_Angeles"

Response

The agent's next step — a reply, proposals, or both

The agent's next step. At least one of proposals or reply is always present in a successful response — proposals at high confidence (optionally with a short reply note), or reply alone when the agent needs more from the user.

proposals
object[]

Validated action-series proposals, ready to accept via POST /instructions. Present only at high confidence.

reply
string

The agent's conversational reply — a clarifying question or confirmation. Present without proposals when the agent needs more from the user; may accompany proposals as a short note.

blockers
object[]

ALPHA — machine-actionable reasons the agent could not complete the request, for the CLIENT APPLICATION rather than the customer. reply explains it in prose, which software cannot branch on: "extend the limit to cover Priya", "I need her bank details" and "that rail is not supported" all arrive as some text. A blocker names the reason as a stable code so the client can act on it — opening its own limit editor with the payee filled in, say — and only then decide what the customer sees. MAY ACCOMPANY PROPOSALS, and routinely does. The common case is a payee who does not exist yet: the turn proposes creating them AND reports that the limit will not reach them, because the client has to do both, in that order — accept the proposal so the payee has an id, then amend the limit to include it. Treat proposals and blockers as independent, never as alternatives. Absent when nothing blocked the turn. ALWAYS switch on code and ignore codes you do not know, as new ones are added over time. Every blocker returned has been re-checked against the server's own data, so a code never reflects only the model's opinion.

conversation_status
enum<string>

How the boundary screen treated this turn. ok is a normal payments turn; warned means the request was off-topic and the customer was warned but may continue; blocked means the conversation has been terminated (repeated off-topic turns or a manipulation attempt) — the client should stop serving it and offer a fresh chat. rejected_input means this message was refused wholesale (e.g. more payees than one conversation supports) and should NOT be added to the conversation history — the reply explains what to resend; the conversation itself continues unaffected.

Available options:
ok,
warned,
blocked,
rejected_input