Overview
No overview information available
Content
# BidPal
## Built at BNB Hack: Buenos Aires
AI Agent powered by x402 to bid on your behalf and buy products on the BNB Chain
A platform enabling buyers and seller agents to communicate using the A2A (Agent-to-Agent) protocol with x402 payment integration that updates it's price dynamically. Every proposal throws a x402 payment request, and once payment is settled on-chain, the buyer acquires the task/product.
## Architecture Overview
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ User │ │ Frontend │ │ Buyer │
│ (Browser) │◄───────►│ (Next.js) │◄───────►│ Agent │
└─────────────┘ └──────────────┘ └─────────────┘
│
│ A2A Protocol
│ HTTP POST /run
│
▼
┌─────────────┐
│ Seller │
│ Agent │
└─────────────┘
```
**Components**:
- **Web UI**: Next.js chat interface with SSE streaming
- **Buyer Agent**: Orchestrator that negotiates and handles payments
- **Seller Agent**: Merchant that offers products and processes payments
## Complete Flow: Negotiation → Payment → Task Acquisition
### 1. Negotiation Flow (A2A Protocol)
```
┌─────────────────────────────────────────────────────────────────┐
│ Negotiation Flow │
└─────────────────────────────────────────────────────────────────┘
User: "get me bnb name for 3 usd or below"
│
├─► Buyer Agent extracts: product="bnb name", maxPrice=3 USD
│
├─► Buyer Agent → Seller Agent (A2A Protocol)
│ POST /run
│ { "newMessage": { "text": "I need bnb name for 0.01 usd or below" } }
│
├─► Seller Agent processes request
│ ├─► handleNegotiationRequest() tool called
│ ├─► Calculates initial offer (1.8x min price)
│ └─► Throws x402PaymentRequiredException (Round 1)
│
├─► MerchantServerExecutor catches exception
│ └─► Returns payment requirements with Round 1 offer
│
├─► Buyer Agent receives Round 1 offer
│ ├─► Compares with max price (3 USD)
│ ├─► Calculates counter-offer (increases gradually)
│ └─► Sends counter-offer to Seller Agent
│
├─► [Negotiation Loop - Up to 5 rounds]
│ │
│ ├─► Round 2: Seller decreases price, Buyer increases offer
│ ├─► Round 3: Price convergence continues
│ ├─► Round 4: Final offers exchanged
│ └─► Round 5: Final offer or agreement reached
│
└─► User accepts price → Proceed to Payment Flow
```
**Negotiation Details**:
- **Buyer Strategy**: Starts low (0.01 USD), gradually increases toward max price
- **Seller Strategy**: Starts high (1.8x min price), gradually decreases toward min
- **Max Rounds**: 5 rounds of negotiation
- **Each Round**: Seller throws x402PaymentRequiredException with current price
### 2. Payment Flow (X402 Protocol)
```
┌─────────────────────────────────────────────────────────────────┐
│ X402 Payment Flow │
└─────────────────────────────────────────────────────────────────┘
User accepts price: "yes"
│
├─► Buyer Agent: confirmPayment() tool called
│
├─► Step 1: Sign Payment (Buyer Side)
│ ├─► Wallet.signPayment()
│ ├─► Check token allowance
│ ├─► Sign EIP-712 payment payload
│ └─► Return signed PaymentPayload
│
│
├─► Step 2: Send Payment Proof to Seller
│ POST /run
│ {
│ "newMessage": {
│ "text": "I want to buy bnb name",
│ "metadata": {
│ "x402.payment.status": "payment-submitted",
│ "x402.payment.payload": <signed_payload>
│ }
│ }
│ }
│
├─► Step 3: Payment Verification (Seller Side)
│ ├─► MerchantServerExecutor receives payment proof
│ ├─► verifyPayment()
│ │ ├─► Send to Facilitator (https://x402.org/facilitator/verify)
│ │ ├─► Verify EIP-712 signature
│ │ ├─► Check token balance and allowance
│ │ └─► Return: { isValid: true, payer: "0x..." }
│ │
│ └─► If valid, proceed to settlement
│
├─► Step 4: Payment Settlement
│ ├─► settlePayment()
│ │ ├─► Send to Facilitator (https://x402.org/facilitator/settle)
│ │ ├─► Execute on-chain settlement
│ │ ├─► Transfer USDC from buyer to seller
│ │ └─► Return: { success: true, transaction: "0x..." }
│ │
│ └─► Payment confirmed on-chain
│
└─► Proceed to Task Acquisition
```
### 3. Task Acquisition Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Task Acquisition Flow │
└─────────────────────────────────────────────────────────────────┘
Payment Settlement Confirmed
│
├─► MerchantServerExecutor.settlePayment() completes
│ └─► Returns: { success: true, transaction: "0x..." }
│
├─► Seller Agent executes contract call
│ ├─► Example: BNB Name NFT Transfer
│ │ contract.safeTransferFrom(
│ │ sellerAddress, // From
│ │ buyerAddress, // To
│ │ tokenId // BNB name token ID
│ │ )
│ │
│ ├─► Transfer asset ownership to buyer
│ └─► Confirm on-chain transfer
│
├─► Task/Product Acquired
│ ├─► Asset ownership transferred to buyer
│ ├─► Order status updated
│ └─► Confirmation sent to buyer agent
│
└─► Buyer receives confirmation
└─► "✅ Payment completed! Your bnb name has been transferred."
```
## Communication Protocol (A2A)
### Buyer → Seller Request Format
```json
POST http://seller-agent:10000/run
{
"appName": "x402_merchant_agent",
"userId": "client-user",
"sessionId": "session-123",
"newMessage": {
"role": "user",
"parts": [{ "text": "I need bnb name for 0.01 usd or below" }]
}
}
```
### Seller → Buyer Response Format
```json
[
{
"invocationId": "task-123",
"errorCode": "x402_payment_required",
"errorData": {
"paymentRequirements": {
"accepts": [{
"maxAmountRequired": "1800000000000000000", // 1.8 USDC (atomic units)
"asset": "0x55d398326f99059fF775485246999027B3197955", // USDC
"payTo": "0x...", // Seller address
"network": "bnb",
"extra": {
"product": { "name": "bnb name" },
"negotiation": {
"round": 1,
"negotiationId": "neg-123",
"minSellPrice": 0.05,
"final": false
}
}
}]
}
},
"content": {
"role": "model",
"parts": [{ "text": "Round 1: I can offer bnb name for 1.8 USDC" }]
}
}
]
```
## Tools Used
### Buyer Agent Tools
- `startNegotiation`: Initiates price negotiation
- `sendMessageToMerchant`: Sends messages to seller
- `confirmPayment`: Signs and executes payment
- `cancelPayment`: Cancels pending payment
### Seller Agent Tools
- `handleNegotiationRequest`: Starts negotiation with initial offer
- `handleCounterOffer`: Processes client counter-offers
- `getProductDetailsAndRequestPayment`: Returns product info and payment requirements
- `checkOrderStatus`: Verifies order after payment
### Core Libraries
- **a2a-x402**: x402 payment protocol implementation
- **adk-typescript**: Agent Development Kit
- **ethers.js**: Blockchain interactions and EIP-712 signing
- **Facilitator Service**: https://x402.org/facilitator (payment verification & settlement)
## Key Points
1. **Every transaction requires x402 payment request**: Seller agent throws `x402PaymentRequiredException` for each interaction
2. **A2A protocol for communication**: Agents communicate via HTTP POST with ADK format
3. **Automatic negotiation**: Buyer and seller agents negotiate prices automatically
4. **Payment verification via Facilitator**: All payments verified through x402.org/facilitator
5. **Task acquired after settlement**: Asset transferred to buyer only after payment is settled on-chain
## License
Apache-2.0
You Might Also Like
No recommendations available