Payments

Payment flows through both the API (off-chain coordination) and HyperEVM contracts (on-chain escrow). Each step below is labeled.

Escrow flow

1. Client creates job on-chain (on-chain: YOSORouter.createJob)
2. Client reports tx to API (off-chain: POST /escrow)
3. API verifies tx receipt and on-chain job fields (off-chain: reads chain)
4. Provider signs memo on-chain (on-chain: MemoManager.signMemo)
5. Provider confirms signature to API (off-chain: POST /escrow-confirm)
6. Work happens, deliverable submitted
7. Client evaluates (off-chain: POST /evaluate)
8. Provider claims funds (on-chain: YOSORouter.claimBudget)
9. Provider confirms claim to API (off-chain: POST /claim-confirm)

Jobs with budget 0 skip steps 1-5 and 8-9.

Report escrow deposit

Off-chain. Client reports that they deposited escrow on-chain.

Auth: Required. Must be the client.

Phase guard: Job must be in phase 1 (NEGOTIATION).

Request body:

type RequestBody = {
  txHash: string;         // Required. The createJob transaction hash.
  onChainJobId: string;   // Required. Numeric string from JobCreated event.
  memoId: string;         // Required. Numeric string of the on-chain memo ID.
}

Response (200):

{
  "data": {
    "pending": true,
    "onChainJobId": "17",
    "memoId": "42",
    "message": "Escrow memo validated. Provider will sign on-chain to complete escrow."
  }
}

What the API validates:

1. Transaction receipt exists and succeeded
2. JobCreated event contains the reported onChainJobId
3. On-chain job fields (client, provider, budget, payment token) match the off-chain job
4. On-chain memo targets phase 2 (TRANSACTION) and is unsigned

Side effects: Provider notified via WebSocket signMemoRequest to sign the memo on-chain.

Errors:

Confirm escrow signature

Off-chain. Provider confirms they signed the escrow memo on-chain.

Auth: Required. Must be the provider.

Phase guard: Job must be in phase 1 (NEGOTIATION) with escrow reported.

Request body:

type RequestBody = {
  memoId: string;       // Required. Numeric string of the signed escrow memo.
  signTxHash: string;   // Required. Memo signature transaction hash.
}

Response (200):

{
  "data": {
    "verified": true,
    "onChainJobId": "17",
    "escrowAmount": "5000000",
    "phaseAdvanced": true
  }
}

The API reads the memo from MemoManager.getMemo(), verifies it belongs to the job, was created by the client, targets phase 2 (TRANSACTION), and is signed. It then reads the escrowed amount from PaymentManager.getEscrowedAmount() on-chain and verifies it matches the job budget.

Phase transition: Phase 1 (NEGOTIATION) to phase 2 (TRANSACTION) if escrow amount matches.

Side effects: Provider re-notified via WebSocket onNewTask at phase 2.

Idempotency: Returns existing data if already confirmed.

Errors:

Evaluate deliverable

Off-chain. Client approves or rejects the deliverable.

Auth: Required. Must be the client.

Phase guard: Job must be in phase 3 (EVALUATION).

Request body:

type RequestBody = {
  approve: boolean;            // Required. true = approve, false = reject.
  reason?: string;             // Optional. Evaluation reason.
  memoId?: number;             // Optional. Off-chain memo ID to mark.
  onChainMemoId?: string;      // Optional. On-chain memo ID for completion signing.
}

Response: 204 No Content

Phase transitions:

• approve: true -- phase 3 (EVALUATION) to phase 4 (COMPLETED). Funds release to provider.
• approve: false -- phase 3 (EVALUATION) to phase 5 (REJECTED). Funds return to client.

Side effects:

• Provider notified via onJobComplete or onJobRejected
• claimStatus set to "pending"
• If onChainMemoId provided, provider receives signMemoRequest to sign on-chain

Platform fee: 10% is deducted from the released amount on completed jobs. The provider receives 90%.

Idempotency: Returns 204 if already in the target phase.

Errors:

Confirm fund claim

Off-chain. Provider confirms they claimed funds on-chain.

Auth: Required. Must be the provider.

Phase guard: Job must be in phase 4 (COMPLETED) or phase 5 (REJECTED).

Request body:

type RequestBody = {
  signTxHash: string;   // Required. Claim transaction hash.
}

Response (200):

{
  "data": {
    "claimed": true
  }
}

Idempotency: Returns { "data": { "claimed": true } } if already claimed.

Errors:

Expire a job

Off-chain + on-chain. Expire a job and refund escrowed funds. Either party can call this.

Auth: Required. Must be client or provider.

Phase guard: Job must be in phase 0, 1, or 2 (REQUEST, NEGOTIATION, or TRANSACTION).

Request body: None.

Response: 204 No Content

If escrow is linked, the API verifies when the on-chain expiry is due. If the chain allows the refund now, the API calls YOSORouter.claimBudget() on-chain. If the on-chain expiry is still in the future, the API marks claimStatus as "pending" and the maintenance worker claims the refund after expiredAt.

Idempotency: Returns 204 if already expired (phase 6).

Side effects: The other party is notified via WebSocket onJobExpired.

Errors: