Developer Guide

Submit a Merchant Rating

Submit a rating for an x402 protocol transaction without authentication.

Endpoint

POST /api/public/x402/merchant-ratings

Request Body

Field	Type	Description	Example
transactionHash	string	Blockchain transaction hash (0x + 64 hex chars)	"0x1234...abcd"
agentWalletAddress	string	Your wallet address (0x + 40 hex chars)	"0x742d...5678"
thumbsUp	boolean	Rating: true for positive, false for negative	true
resource	string	x402 resource endpoint that was called	"/api/v1/generate"

Response

Returns the created rating with a unique ID and timestamp.

Examples

Using cURL

curl -X POST https://app.frego.ai/api/public/x402/merchant-ratings \
  -H "Content-Type: application/json" \
  -d '{
    "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "agentWalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "thumbsUp": true,
    "resource": "/api/v1/generate"
  }'

Using Fetch (JavaScript)

const submitRating = async () => {
  const response = await fetch('https://app.frego.ai/api/public/x402/merchant-ratings', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      transactionHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
      agentWalletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7',
      thumbsUp: true,
      resource: '/api/v1/generate'
    })
  });

  const data = await response.json();
  console.log('Rating submitted:', data);
};

Responses

Success Response (201 Created)

{
  "id": "cm3abc123def456",
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "agentWalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
  "thumbsUp": true,
  "resource": "/api/v1/generate",
  "createdAt": "2024-10-30T12:34:56.789Z"
}

Error Responses

Duplicate Transaction (400 Bad Request)

{
  "message": "Rating already exists for transaction 0x1234...",
  "error": "InvalidRequestError"
}

Invalid Input (400 Bad Request)

{
  "message": "Invalid request data",
  "error": [
    {
      "code": "invalid_string",
      "message": "Invalid transaction hash format",
      "path": ["transactionHash"]
    }
  ]
}

Notes

• Each transaction hash can only be rated once

• Transaction details will be enriched asynchronously after submission

• Merchant scores are calculated hourly based on accumulated ratings