Get Agent Reputation — GET /api/agent/reputation

The reputation endpoint gives you a summary of an agent’s on-chain reputation activity, derived from the agent’s payment history stored in FlareHQ’s database. For a given ERC-8004 agent, it returns an estimated reputation score (0–100), the total number of payments made, the number of successful payments, the cumulative USDC volume, and the Reputation Registry contract address used for on-chain reputation writes. The response also includes up to 10 of the agent’s most recent payments for context.

This is a public lookup — GET requests bypass API key authentication. The estimatedScore is computed from FlareHQ’s database of the agent’s payment history. For the authoritative on-chain reputation score written by third-party validators, read the getReputation view function on the Reputation Registry contract directly (address below).

Endpoint

GET https://flarehq.xyz/api/agent/reputation?agentId={tokenId}

Request

Headers

Header	Required	Description
`x-api-key`	No	Your FlareHQ API key (`fhq_sec_test_...`). GET requests are public and do not require one, but the key is accepted if provided

Query Parameters

Pass either agentId or scaAddress — at least one is required.

string

The ERC-8004 token ID of the agent (e.g. "68210"). Equivalent to {tokenId} in the agent identifier 8004:5042:{tokenId}.

string

The agent’s Circle SCA wallet address (e.g. 0xA1B2C3D4E5F6...). Use this instead of agentId when you only have the wallet address.

Response

boolean

true when the agent was found and the reputation summary was assembled.

object

Core identity record for the agent.

Show agent fields

string

The ERC-8004 token ID of the agent.

string

Human-readable agent name set at deployment time.

string

The agent’s Circle SCA wallet address.

string

Deployment status, e.g. "ACTIVE_AGENT_PROVISIONED".

object

Reputation metrics computed from the agent’s payment history in FlareHQ’s database.

Show reputationSummary fields

number

Estimated reputation score from 0–100, computed as the percentage of the agent’s payments that succeeded (round(successful / total * 100)). Returns 0 when the agent has no payment history.

number

Total number of payment log entries found for the agent, across all statuses.

number

Count of payments with status SUCCESS.

number

Cumulative USDC amount of successful payments, as a float rounded to 6 decimal places.

string

The ERC-8004 Reputation Registry contract address on Arc testnet where on-chain reputation feedback is recorded: 0x8004B663056A597Dffe9eCcC1965A193B7388713. Production runs on Arc Mainnet — confirm the production registry address with the operator.

array

Up to 10 most recent payment log entries initiated by the agent’s SCA address, in descending timestamp order. Each entry mirrors the stored payment log record (e.g. reference, amount, currency, status, timestamp).

string

Human-readable summary of the lookup, e.g. "Agent #68210 reputation summary. For onchain reputation, check Arc Explorer."

Examples

curl -X GET "https://flarehq.xyz/api/agent/reputation?agentId=68210"

curl -X GET "https://flarehq.xyz/api/agent/reputation?scaAddress=0xA1B2C3D4E5F6..."

const res = await fetch(
  "https://flarehq.xyz/api/agent/reputation?agentId=68210"
);
const { success, reputationSummary, recentPayments } = await res.json();
console.log(`Score: ${reputationSummary.estimatedScore}/100`);
console.log(`Volume: ${reputationSummary.totalVolumeUSDC} USDC`);

Success Response

{
  "success": true,
  "agent": {
    "tokenId": "68210",
    "name": "DeFi Analytics Agent",
    "scaAddress": "0xA1B2C3D4E5F6...",
    "status": "ACTIVE_AGENT_PROVISIONED"
  },
  "reputationSummary": {
    "estimatedScore": 88,
    "totalPayments": 42,
    "successfulPayments": 37,
    "totalVolumeUSDC": 0.042,
    "reputationRegistryAddress": "0x8004B663056A597Dffe9eCcC1965A193B7388713"
  },
  "recentPayments": [
    {
      "id": "pay_01HZ...",
      "reference": "arc_ref_k7x2m9lp4d8f1q2z",
      "amount": 0.001,
      "currency": "USDC",
      "status": "SUCCESS",
      "timestamp": "2026-08-10T14:23:00.000Z"
    }
  ],
  "message": "Agent #68210 reputation summary. For onchain reputation, check Arc Explorer."
}

Error Responses

{
  "success": false,
  "error": "Pass agentId or scaAddress as query param."
}

{
  "success": false,
  "error": "Agent not found."
}

Notes

The estimatedScore is derived from payment history in FlareHQ’s database and is not the authoritative on-chain score. Third-party validators record reputation on-chain via giveFeedback() on the Reputation Registry at 0x8004B663056A597Dffe9eCcC1965A193B7388713 (documented Arc Testnet deployment, chain ID 5042002). Production runs on Arc Mainnet — confirm the production registry address with the operator. Read the getReputation(tokenId) view function on that contract for the authoritative score.

Use this endpoint to power reputation badges, agent marketplace sorting, or vetting dashboards. Because it is public, you can call it from a browser or server without storing API credentials.

recentPayments only includes payments where the agent’s SCA address is recorded as the sender. Payments received by the agent are not reflected in these metrics.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Get Agent Reputation — GET /api/agent/reputation

Endpoint

Request

Headers

Query Parameters

Response

Examples

Success Response

Error Responses

Notes

​Endpoint

​Request

​Headers

​Query Parameters

​Response

​Examples

​Success Response

​Error Responses

​Notes

Endpoint

Request

Headers

Query Parameters

Response

Examples

Success Response

Error Responses

Notes