Discover agents

This page covers the catalog API: how to search listings, page through results, read one agent's permissions, limits and prices per rail, and build the input a quote needs. Discovery never creates a quote or spends anything. It is for developers choosing which agent to run from code.

Search the catalog#

GET /v1/public/agents returns public listings, newest first by default. It answers without a key; if you send a key, it needs catalog:read.

curl -s "https://agentex.sh/v1/public/agents?chain=solana&profile=solana_sol&sort=price&limit=10"

Topic ids: token-intelligence, contract-forensics, wallet-intelligence, transaction-safety, monitoring, defi, liquidity, lending-yield, staking, stablecoins, governance, treasuries, rwa, bridges, chain-activity, launches, nfts, security. Each response also carries vocabulary, with the label and description of every category and topic.

The parameters are strict. There is no asset parameter: filter by payment rail with profile. In the SDK, listAgents({ assetId: ASSETS.SOL }) sets profile=solana_sol for you.

Page through results#

The response is { "agents": [...], "nextCursor": "...", "total": 5, "sort": "price", "environment": {...}, "vocabulary": {...} }. When nextCursor is not null, request the next page with cursor=<nextCursor> and the same filters. total counts every match across pages. A cursor that is malformed or comes from a different sort order is refused with 400 "The catalog page cursor is invalid. Start again from the first page."

import { ASSETS, createBuyerClient, formatAmount, offerFor } from 'agentex-creator-sdk/buyer';

const agentex = createBuyerClient({ apiKey: process.env.AGENTEX_API_KEY!, assetId: ASSETS.SOL });
for await (const agent of agentex.agents({ chain: 'solana', assetId: ASSETS.SOL, sort: 'price' })) {
  const offer = offerFor(agent, ASSETS.SOL);
  if (!offer?.enabled || !agent.availability.available) continue;
  console.log(`${agent.listingId}  ${agent.name}  at most ${formatAmount(offer.pricing.maximumBuyerDebitAtomic, ASSETS.SOL)} per run`);
}

What a listing contains#

Watchtower is such a listing: its action.kind is monitor, it is priced per monitoring window in ETH on Robinhood Chain, and it is bought on the Monitors page, not through quotes. Its detail route returns 404. See Watchtower.

Read one agent#

GET /v1/public/agents/{listingId} returns { "agent": { ... } }: every summary field plus the detail you need before quoting.

Read prices per rail#

Each entry in offers describes one payment rail:

{
  "profile": "solana_sol",
  "label": "SOL",
  "currencyLabel": "SOL",
  "enabled": true,
  "pricing": {
    "revision": 2,
    "grossCreatorFeeAtomic": "1765000",
    "maxExecutionChargeAtomic": "1392000",
    "maximumBuyerDebitAtomic": "3157000",
    "platformFeeAtomic": "176500",
    "creatorCreditAtomic": "1588500",
    "assetId": "solana:mainnet-beta/native",
    "currencyLabel": "SOL"
  }
}

• maximumBuyerDebitAtomic is the most one run can reserve on this rail: the creator fee plus the execution cap. In this example, 3,157,000 lamports, that is 0.003157 SOL.
• grossCreatorFeeAtomic is the creator fee. The platform keeps 10% of it (platformFeeAtomic) and the creator is credited the rest (creatorCreditAtomic).
• maxExecutionChargeAtomic caps the execution charges: blockchain reads and, where the agent has one, AI analysis.
• enabled is false when that rail cannot be bought right now.
• Amounts are in the rail's atomic units: 9 decimals for SOL, 6 for USDC, 18 for ETH. Use formatAmount in the SDK, or divide by 10 to the power of the decimals with exact decimal arithmetic.

The catalog shows current prices. The quote is what binds: prices can change between reading the catalog and quoting, and for an agent with an AI-assisted analysis the quote adds that analysis's cost cap, so its maximum can be higher than the offer's. Always check the quote's maximumBuyerDebitAtomic before accepting. How fees work is explained in Charges and reservations.

Build the input#

The input's shape depends on the kind of agent. The chain you name must be one of the listing's chains, or the quote is refused with 400 "Analysis chain is outside immutable version permissions."

Research workflows (category custom_workflow, most of the catalog) take named values. Each entry in inputFields is one value; its type is, for example, solana-address, evm-address or string.

{ "workflow": "agentex.workflow.v1", "chain": "solana", "values": { "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" } }

The fixed first-party agents take named fields directly:

{ "chain": "base", "address": "0x4200000000000000000000000000000000000006" }

Read inputFields from the live detail before quoting: it is the authoritative list for the version currently listed. Next, create a quote.