Orders API

Manage orders and process payment fulfillment.

Get Order

Retrieve an order by ID.

GET /api/orders/:id

Response

{
  "success": true,
  "responseObject": {
    "id": "ord_abc123",
    "sessionId": "sess_xyz789",
    "merchantId": "merch_abc123",
    "status": "SIGNAL_MINED",
    "intentHash": "0x1234567890abcdef...",
    "signalTx": "0xabcdef1234567890...",
    "fulfillTx": null,
    "paymentPlatform": "venmo",
    "fiatCurrency": "USD",
    "amountUsdc": "50.00",
    "conversionRate": "1.00",
    "recipient": "@merchant-venmo",
    "quote": {
      "fiatAmount": "50.00",
      "tokenAmount": "50000000",
      "payeeAddress": "@merchant-venmo"
    },
    "expiresAt": "2024-01-15T11:00:00.000Z",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:05:00.000Z"
  }
}

---

Fulfill Order

Submit a payment proof to verify and fulfill the order.

POST /api/orders/fulfill

Request

{
  "intentHash": "0x1234567890abcdef...",
  "proof": {
    "identifier": "...",
    "claimData": { ... },
    "signatures": [ ... ],
    "witnesses": [ ... ]
  }
}

Field	Type	Required	Description
intentHash	string	Yes	The on-chain intent hash
proof	object	Yes	Reclaim proof object

Success Response

{
  "success": true,
  "message": "Order fulfilled successfully",
  "responseObject": {
    "order": {
      "id": "ord_abc123",
      "status": "FULFILLED",
      "fulfillTx": "0x9876543210fedcba...",
      ...
    },
    "proofAttemptId": "proof_xyz789",
    "txHash": "0x9876543210fedcba..."
  }
}

Error Response

When proof verification fails, users can retry with a new proof:

{
  "success": false,
  "message": "Payment proof validation failed",
  "responseObject": {
    "proofAttemptId": "proof_xyz789",
    "errorCode": "PROOF_INVALID",
    "errorMessage": "Payment amount does not match intent",
    "canRetry": true
  }
}

Error Code	Description	Can Retry
PROOF_INVALID	Proof verification failed	Yes
PROOF_EXPIRED	Proof timestamp too old	Yes
FULFILL_TIMEOUT	On-chain tx timed out	No
FULFILL_REVERTED	On-chain tx reverted	No
ORDER_NOT_FOUND	Order doesn't exist	No
ORDER_ALREADY_FULFILLED	Already completed	No

---

Get Proof Attempts

Get all proof attempts for an order.

GET /api/orders/:id/proof-attempts

Response

{
  "success": true,
  "responseObject": {
    "proofAttempts": [
      {
        "id": "proof_xyz789",
        "orderId": "ord_abc123",
        "intentHash": "0x1234...",
        "status": "FULFILLED",
        "submittedAt": "2024-01-15T10:10:00.000Z",
        "verifiedAt": "2024-01-15T10:10:05.000Z",
        "txHash": "0x9876...",
        "txConfirmedAt": "2024-01-15T10:10:30.000Z"
      },
      {
        "id": "proof_abc456",
        "orderId": "ord_abc123",
        "intentHash": "0x1234...",
        "status": "REJECTED",
        "submittedAt": "2024-01-15T10:08:00.000Z",
        "verificationError": "PROOF_INVALID",
        "verificationMessage": "Payment amount does not match"
      }
    ]
  }
}

---

Order Status Values

Status	Description
SESSION_CREATED	Initial state
SIGNAL_SENT	Intent tx submitted
SIGNAL_MINED	Intent confirmed on-chain
PAYMENT_SENT	User marked payment sent
PROOF_VERIFIED	Proof verified off-chain
PROOF_SUBMITTED	Proof submitted to chain
FULFILL_SUBMITTED	Fulfillment tx submitted
FULFILLED	Payment complete, USDC transferred
CANCELLED	Order cancelled
EXPIRED	Order expired
FAILED	Order failed

Order Lifecycle

SESSION_CREATED
      ↓
SIGNAL_SENT → (tx pending)
      ↓
SIGNAL_MINED → (intent on-chain)
      ↓
PAYMENT_SENT → (user sent fiat)
      ↓
PROOF_VERIFIED → (proof checked)
      ↓
PROOF_SUBMITTED → (proof on-chain)
      ↓
FULFILL_SUBMITTED → (tx pending)
      ↓
FULFILLED ✓

Alternative paths:

• SIGNAL_MINED → EXPIRED (timeout)
• SIGNAL_MINED → CANCELLED (user cancelled)
• PROOF_VERIFIED → FAILED (tx reverted)