REST API

Direct endpoints — create invoices, authorize checkouts, query state. Server-to-server.

The SDK is a thin wrapper over these. If you're not on Node, talk to the API directly.

Base URL: https://arcorapay.xyz

Auth: API key in X-Arcora-Api-Key header. Created at /m/settings.

`POST /api/invoices`

Create an invoice and stage it on-chain.

Request

POST /api/invoices HTTP/1.1
Content-Type: application/json
X-Arcora-Api-Key: ak_live_...

{
  "amountUsdc":  49.99,
  "payInToken":  "EURC",
  "successUrl":  "https://yourshop.com/order/123/success",
  "cancelUrl":   "https://yourshop.com/order/123/cancel",
  "metadata":    { "orderId": "123" }
}

Routes to the live custody-escrow gateway (ArcFXGateway at 0x07BAC123…aE3a3). The legacy ?engine= selector is gone (pre-cutover gateways retired); every invoice records the gateway address it was created against.

Response

HTTP/1.1 201 Created

{
  "invoiceId": "0x4f3a...",
  "url":       "https://arcorapay.xyz/i/0x4f3a..."
}

Error responses

Status	Code	Notes
400	`bad_body`	Body shape rejected by Zod schema.
401	`missing_api_key` / `invalid_api_key`	Header missing or unrecognised.
403	`MERCHANT_PAYOUT_BLOCKED`	Plan-5 sanctions screen rejected the merchant payout address.
412	`delegate_not_authorized`	Server hot wallet hasn't been authorized for `createInvoiceFor`.
502	`chain_error`	On-chain tx reverted. `detail` carries the short message.
503	`compliance_unavailable`	Compliance provider 5xx and `COMPLIANCE_FAIL_OPEN_FOR_INVOICE=false`.

`POST /api/checkout/authorize`

Compliance gate — fired by the hosted checkout after the customer connects their wallet, before signing.

Request

POST /api/checkout/authorize HTTP/1.1
Content-Type: application/json

{
  "invoiceId": "0x4f3a...",
  "address":   "0x3687d36e8b0fee06bcd935b6312ca5b59f8e4317"
}

Response

// allow
{ "decision": "allow", "screenedAt": "2026-05-03T...", "ttlSeconds": 86400 }

// review
{
  "decision":       "review",
  "ticketId":       "rev_abc...",
  "reason":         "Compliance review required — we'll email the merchant within 24h.",
  "supportContact": "compliance@arcorapay.xyz"
}

// reject (sanctions or high risk)
{
  "decision": "reject",
  "code":     "SANCTIONED_WALLET" | "HIGH_RISK_WALLET",
  "reason":   "This wallet can't be used for this payment."
}

On testnet the active provider is Noop — every wallet returns allow.

`POST /api/checkout/submit`

Customer-side Permit2 submission. The hosted checkout calls this once the customer signs; the relayer then drains the queue. You don't typically call this yourself unless building a non-hosted checkout.

{
  "invoiceId":         "0x...",
  "payer":             "0x...",
  "payInToken":        "0x...",
  "amountIn":          "49990000",
  "permit2Data":       { "nonce": "1", "deadline": "...", "witness": "0x...", "witnessTypeString": "..." },
  "permit2Signature":  "0x..."
}

`GET /api/checkout/status/{submissionId}`

Poll the relayer queue for settlement state.

{
  "status":        "pending" | "processing" | "settled" | "refunded" | "failed",
  "settleTxHash": "0x..." | null,
  "refundTxHash": "0x..." | null,
  "error":         string | null
}

`POST /api/checkout/quote`

Live quote from App Kit Swap on Arc. Used by hosted checkout. Supports two modes —amountIn for forward quotes (caller knows what they're paying), andtargetOutput for reverse quotes (caller knows the merchant floor; the response carries the cushioned amountIn the customer should sign for).

POST /api/checkout/quote HTTP/1.1
Content-Type: application/json

{
  "payInToken":   "EURC",
  "payoutToken":  "USDC",
  "targetOutput": "49.99",
  "slippageBps":  250
}

Response

{
  "payInToken":      "EURC",
  "payoutToken":     "USDC",
  "amountIn":        "46.045679",
  "estimatedOutput": "49.99",
  "stopLimit":       "49.49",
  "fees":            [{ "token": "USDC", "amount": "0.5", "type": "providerFee" }],
  "ttlSeconds":      30,
  "issuedAt":        "2026-05-02T..."
}

The legacy GET /api/quote?from&to&amountIn endpoint reads the v0.6 on-chain pool and is kept for read-only callers; new integrations should use/api/checkout/quote.

`GET /api/merchant/treasury`

Authenticated (SIWE session) merchant treasury rollup. Used by /m/treasury.

`GET /api/merchant/compliance`

Authenticated. Returns the merchant's own onboarding screen + customer review queue. Used by /m/compliance.