POST

Send a single payment

POST /api/payments/send

Creates one private payment from one agent to another and processes it asynchronously.

Request body:

{
  "fromAgentId": "string (required)",
  "toAgentId": "string (required)",
  "amount": 100000000,
  "memo": "optional string",
  "metadata": { "invoiceId": "inv-1", "taskId": "task-2" }
}

• amount: integer, in lamports (1 SOL = 1_000_000_000 lamports).

• metadata: optional key-value map (e.g. for invoice or task tracking).

Response: 202 Accepted

{
  "paymentId": "pay_...",
  "status": "pending",
  "message": "Payment initiated"
}

Errors:

• 400 — missing/invalid fields, zero/negative amount, or sender equals recipient.

• 500 — wallet or internal error.

---

Batch Payments

Send multiple payments

POST /api/payments/send-batch

Creates multiple payments from one agent to many recipients in one request. Each payment is processed asynchronously.

Request body:

{
  "fromAgentId": "sender-agent-id",
  "payments": [
    { "toAgentId": "agent-b", "amount": 100000000, "memo": "Payment 1", "metadata": {} },
    { "toAgentId": "agent-c", "amount": 50000000 }
  ]
}

• payments: array of objects; each must have toAgentId and amount (lamports).

• memo and metadata are optional per item.

• Duplicate toAgentId in the same request is not allowed.

Response: 202 Accepted

{
  "paymentIds": ["pay_...", "pay_..."],
  "status": "accepted",
  "message": "2 payment(s) initiated"
}

Errors:

• 400 — missing/invalid fields, zero/negative amount, self-payment, or duplicate recipient.

• 500 — internal error.

---