Ask the user to approve a transfer, without spending funds.

POST /api/v1/apps/transfer/request

Ask the user to approve a transfer, without spending funds.

cURL

curl --request POST \
  --url https://api.example.com/api/v1/apps/transfer/request \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "contactId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quoteId": "<string>",
  "invoiceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 123,
  "memo": "<string>"
}
'

202

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "requested",
  "txHash": "<string>",
  "transactionId": "<string>",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "appId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requestedByUserId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contactId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quoteId": "<string>",
  "invoiceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 123,
  "memo": "<string>",
  "requestedTime": "2023-11-07T05:31:56Z",
  "chatId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "approvalUrl": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string | null

x-api-key · string · required

Body

application/json

What is being sent, and to whom.

Exactly one of contactId / quoteId / invoiceId must be set (mirrors the /mcp/transfer body). amount is required when contactId is the dispatch path; otherwise it is derived from the referenced invoice or quote.

contactId · string<uuid> | null

quoteId · string | null

invoiceId · string<uuid> | null

amount · number | null

memo · string | null

Response

202

application/json

Successful Response

One outcome shape for both ways a transfer attempt can end.

Spent straight away: txHash only. Needs approval: the request that was filed, with the deep link to approve it. transactionId appears once an approved transfer has been reported back. A decline reason is not a field — it is a message in chatId, the request's thread.

id · string<uuid> | null

status · enum<string> | null

Client-facing status of a transfer_request proposal.

The record is a proposal (seven statuses); this is the short vocabulary the API keeps for the agent and the web app, mapped from ProposalStatus by :meth:from_proposal.

Available options: requested, approved, declined, failed

txHash · string | null

transactionId · string | null

accountId · string<uuid> | null

appId · string<uuid> | null

requestedByUserId · string<uuid> | null

contactId · string<uuid> | null

quoteId · string | null

invoiceId · string<uuid> | null

amount · number | null

memo · string | null

requestedTime · string<date-time> | null

chatId · string<uuid> | null

approvalUrl · string | null