Client SDK with Receipt Verification

[AnkanMisra]

Problem

There's no official way for clients to integrate with MicroAI-Paygate. Users need a TypeScript SDK to sign payments and verify receipts.

Architecture

flowchart LR
    subgraph Client
        A[User App] --> B[Paygate SDK]
        B --> C[ethers.js]
    end
    
    subgraph Server
        D[Gateway]
        E[Verifier]
    end
    
    B -->|1. Sign Payment| D
    D -->|2. Verify| E
    E -->|3. Valid| D
    D -->|4. Receipt + Response| B
    B -->|5. Verify Receipt| B

Loading

SDK Flow

sequenceDiagram
    participant App
    participant SDK
    participant Gateway
    
    App->>SDK: request("/api/ai/summarize", body)
    SDK->>Gateway: POST (no signature)
    Gateway-->>SDK: 402 + PaymentContext
    SDK->>SDK: Sign with ethers.js
    SDK->>Gateway: POST + X-402-Signature
    Gateway-->>SDK: 200 + Receipt
    SDK->>SDK: Verify receipt signature
    SDK-->>App: Response + verified receipt

Loading

Implementation

New directory: sdk/typescript/

// sdk/typescript/src/index.ts
export class PaygateClient {
  constructor(private serverUrl: string, private signer: ethers.Signer) {}
  
  async signPayment(context: PaymentContext): Promise<string>
  async verifyReceipt(receipt: SignedReceipt): Promise<boolean>
  async request<T>(endpoint: string, body: any): Promise<T>
}

Acceptance Criteria

• Package structure with package.json
• signPayment() creates valid EIP-712 signatures
• verifyReceipt() validates server signatures (Keccak256)
• Works with receipts from Go gateway
• Unit tests with real receipt fixtures
• Example usage in README

Testing

cd sdk/typescript && bun test

Must test against actual receipts from running server

[vishal0316]

@AnkanMisra can you assign me this here is my approch

SDK Implementation Plan

Core SDK

• Create sdk/typescript/ with proper package structure
  • Tooling: tsup + vitest
• Implement PaygateClient class with:
  • signPayment()
    • EIP-712 signing via ethers.js
  • request()
    • Auto-handle 402 Payment Required flow
    • Flow: try → get context → sign → retry
  • verifyReceipt()
    • Reuse existing verify-receipt.ts logic
• Export types from existing receipt interfaces

Testing

• Unit tests using fixture receipts from the actual gateway
• Integration test against a running server
• Verified compatibility with Go backend’s crypto.Sign format

Open Questions

• Should the SDK handle wallet management or accept an external signer?
• Is payment execution required, or only signature generation?

[vishal0316]

@AnkanMisra just for remind

[AnkanMisra]

@AnkanMisra just for remind
My health is not that well, I'll review all pr on Sunday

[vishal0316]

@AnkanMisra just for remind
My health is not that well, I'll review all pr on Sunday

take care get well soon

[AnkanMisra]

@vishal0316 you can send a pr

@AnkanMisra can you assign me this here is my approch

SDK Implementation Plan

Core SDK

* Create `sdk/typescript/` with proper package structure
  
  * Tooling: **tsup** + **vitest**

* Implement `PaygateClient` class with:
  
  * `signPayment()`
    
    * EIP-712 signing via **ethers.js**
  * `request()`
    
    * Auto-handle **402 Payment Required** flow
    * Flow: `try → get context → sign → retry`
  * `verifyReceipt()`
    
    * Reuse existing `verify-receipt.ts` logic

* Export types from existing receipt interfaces

Testing

* Unit tests using fixture receipts from the actual gateway

* Integration test against a running server

* Verified compatibility with Go backend’s `crypto.Sign` format

Open Questions

* Should the SDK handle wallet management or accept an external signer?

* Is payment execution required, or only signature generation?

@vishal0316 proposed structure sounds solid

Here are your answers:

1. Accept an External Signer

The SDK should be agnostic to the wallet provider. It should accept an abstract Signer (e.g., from ethers or viem) in the constructor or method calls.

• Why: We want this to work with MetaMask, Privy, or backend bots. The SDK shouldn't handle private keys directly unless it's a specific helper class for server-side bots.

2. Signature Generation Only

• Context: The MicroAI-Paygate protocol uses off-chain EIP-712 signatures to grant access. We do not broadcast a blockchain transaction for every API request (that would be too slow).
• Flow: The client receives the 402 headers, signs the parameters (amount, nonce, etc.) using the user's wallet, and sends the signature back in the header. The Go gateway + Rust verifier handles the rest.
• Requirement: The SDK just needs to correctly format the Typed Data and request the signature from the signer.

[AnkanMisra]

@vishal0316 would you continue solving this?

[vishal0316]

@vishal0316 would you continue solving this?

sorry unassign me