Build
Hosted payment API
A framework-neutral endpoint for protected Arc payments. Authenticate with the agent key returned at provisioning.
Request
POST
/v1/paymentsSubmit a payment proposal for the vault assigned to the authenticated agent.
JSON body
{
"payeeAddress": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
"amountUsdc": 1.5,
"actionType": 1,
"idempotencyKey": "order-123"
}amountUsdc is positive and supports at most six decimal places. actionType is an integer from 0–255 whose corresponding bit must be enabled by the vault.
Response
example
{
"id": "pr_…",
"status": "BLOCKED",
"amountUsdc": 1.5,
"payeeAddress": "0x…",
"blockReasonCode": "RECIPIENT_NOT_ALLOWLISTED",
"blockReasonDescription": "The destination is not approved by this vault.",
"txHash": "0x…",
"explorerUrl": "https://testnet.arcscan.app/tx/0x…"
}A 2xx response is not automatically a transfer
Always branch on
status. A policy-blocked on-chain attempt may be a confirmed transaction that moved zero funds.Idempotency
Send a stable key for each logical purchase. Repeating the same key in the same workspace returns the stored result instead of initiating another payment. Keep keys non-empty and under 200 characters.
Common block reasons
VAULT_PAUSEDThe owner has paused payments.AGENT_KEY_EXPIREDThe authorized agent key has expired.RECIPIENT_NOT_ALLOWLISTEDThe destination is not approved.ACTION_NOT_ALLOWEDThe action bit is disabled.PER_TX_CAP_EXCEEDEDThe request is larger than the per-payment cap.DAILY_CAP_EXCEEDEDThe UTC-day allowance is exhausted.INSUFFICIENT_BALANCEThe vault cannot cover the request.