Architecture - AbabilPay Docs

Overview

Ababil is a payment infrastructure layer built on the x402 protocol. It sits between merchants and buyers, providing the API, dashboard, and on-chain relay needed to accept USDC payments — without ever holding funds. The system is designed around three principles:

Non-custodial — USDC moves peer-to-peer, directly from buyer wallet to merchant dashboard wallet. Ababil relays the transaction but never holds or routes funds through its own accounts.
Chain-agnostic — a single payment intent covers all chains the merchant has registered wallets on. The buyer picks the chain at payment time.
Agent-ready — EIP-3009 authorizations require nothing beyond a private key, making fully autonomous AI agent payments possible with no browser or approval flow.

The x402 Protocol Triangle

Every payment involves three roles:

┌─────────────┐        creates intent        ┌──────────────┐
│   Merchant  │ ──────────────────────────── │   Ababil     │
│  Dashboard  │                              │   (Relay)    │
└─────────────┘                              └──────────────┘
       ▲                                            │
       │  USDC lands in                             │ verifies signature
       │  merchant wallet                           │ submits on-chain tx
       │                                            ▼
                                           ┌──────────────┐
                                           │    Buyer     │
                                           │ (or AI Agent)│
                                           └──────────────┘
                                            signs EIP-3009
                                            authorization

Role	Responsibility
Merchant	Creates payment intents via API. Registers wallets on supported chains from the dashboard. Receives USDC directly into their dashboard wallet on settlement.
Buyer	Signs a `TransferWithAuthorization` EIP-3009 message (EVM) or SPL transaction (Solana). No token approvals required.
Ababil	Validates the signature, checks buyer balance, and submits `transferWithAuthorization` on-chain via relay EOA. Marks the intent `paid` on confirmation.

Payment Flow

1. Merchant backend
      POST /api/v1/x402/intents { amount_usdc, ... }
      ← intent_id, checkout_url, payment_requirements

2. Buyer (browser or AI agent)
      Signs TransferWithAuthorization typed data
      with their private key / browser wallet

3. Ababil
      Receives signed payload via POST /api/v1/x402/pay
      Verifies EIP-3009 signature (viem verifyTypedData)
      Checks buyer USDC balance ≥ maxAmountRequired
      Confirms intent is pending and not expired
      Calls usdc.transferWithAuthorization(...) on-chain
      USDC moves buyer → merchant wallet (peer-to-peer)
      Marks intent paid in DB with tx_hash and paid_at

4. Merchant backend
      GET /api/v1/x402/intents/{id}
      ← status: "paid", tx_hash, paid_at
      Fulfils order

EIP-3009 — How the Authorization Works

EIP-3009 (transferWithAuthorization) is a standard on Circle USDC contracts that allows a signed message to authorize a USDC transfer, without requiring a separate on-chain approve transaction first. The buyer signs an EIP-712 typed data message containing:

Field	Description
`from`	Buyer wallet address
`to`	Merchant wallet address (`payTo` from `payment_requirements`)
`value`	Transfer amount in atomic USDC units
`validAfter`	Earliest timestamp the authorization is valid (typically `0`)
`validBefore`	Expiry timestamp (typically `now + 900s`)
`nonce`	Random `bytes32` — used once, permanently recorded by the USDC contract

Ababil’s relay wallet submits this signed data to the USDC contract. The contract verifies the signature and executes the transfer atomically — no separate approval step, no intermediate account.

Supported Chains (Testnet v1)

Network	Chain ID	Role
Base Sepolia	`84532`	EVM — EIP-3009
Ethereum Sepolia	`11155111`	EVM — EIP-3009
Arc Testnet	`5042002`	EVM — EIP-3009
Solana Devnet	N/A	SPL token transfer

All EVM chains use the same TransferWithAuthorization signing flow. Solana uses a two-step flow: Ababil builds the unsigned SPL transfer transaction, the buyer signs it with their Solana wallet, and the signed transaction is submitted via /pay.

Merchant Dashboard Wallet

Each merchant registers one or more wallets from the Ababilpay Dashboard. These are the destination addresses for all USDC settlements.

Wallets are registered per chain — a merchant can have a Base Sepolia wallet and a Solana Devnet wallet simultaneously.
When a payment intent is created, payment_requirements is automatically populated with an entry for every chain the merchant has a registered wallet on.
USDC is transferred directly to the registered wallet address on settlement — it never passes through Ababil.

API Authentication Model

All API calls are authenticated with a merchant-scoped Bearer key:

Authorization: Bearer sk_test_...

The API key identifies which merchant the intent belongs to and which wallets to include in payment_requirements. Keys are created and revoked from the Dashboard → API Keys.

Integration Paths

Ababil supports two integration patterns that share the same intent creation endpoint:

	Hosted Gateway	Custom Integration
Use case	Human buyers, e-commerce	AI agents, white-label UIs
Buyer UX	Ababil-hosted checkout page	Your own frontend
Signing	Handled by Ababil checkout	Handled by your code
Settlement call	Automatic (inside checkout)	`POST /api/v1/x402/pay`
AI agent support	✗	✓

See Hosted Gateway and Custom Integration for full implementation details.

​Overview

​The x402 Protocol Triangle

​Payment Flow

​EIP-3009 — How the Authorization Works

​Supported Chains (Testnet v1)

​Merchant Dashboard Wallet

​API Authentication Model

​Integration Paths