Examples

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`);
}

import os
from decimal import Decimal

import requests

API = "https://agentex.sh/v1"
headers = {"Authorization": f"Bearer {os.environ['AGENTEX_API_KEY']}"}
params = {"chain": "solana", "profile": "solana_sol", "sort": "price", "limit": 50}

cursor = None
while True:
    query = {**params, "cursor": cursor} if cursor else params
    response = requests.get(f"{API}/public/agents", headers=headers, params=query, timeout=15)
    response.raise_for_status()
    page = response.json()
    for agent in page["agents"]:
        offer = next((o for o in agent["offers"] if o["profile"] == "solana_sol" and o["enabled"]), None)
        if offer and agent["availability"]["available"]:
            price = Decimal(offer["pricing"]["maximumBuyerDebitAtomic"]) / Decimal(10**9)
            print(agent["listingId"], agent["name"], f"at most {price} SOL per run")
    cursor = page["nextCursor"]
    if not cursor:
        break

curl -s -H "Authorization: Bearer $AGENTEX_API_KEY" \
  "https://agentex.sh/v1/public/agents?chain=solana&profile=solana_sol&sort=price&limit=50"

import { ASSETS, AgentexApiError, createBuyerClient, evidenceFor, offerFor, parseAmount, workflowInput } from 'agentex-creator-sdk/buyer';

const SOL = ASSETS.SOL;
const agentex = createBuyerClient({ apiKey: process.env.AGENTEX_API_KEY!, assetId: SOL });

const { agents } = await agentex.listAgents({ q: 'Solana Token Safety Check', chain: 'solana', assetId: SOL });
const agent = agents.find(item => offerFor(item, SOL)?.enabled);
if (!agent) throw new Error('No listing matching this search accepts SOL.');

try {
  const outcome = await agentex.research({
    listingId: agent.listingId,
    input: workflowInput('solana', { mint: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263' }),
    maxDebitAtomic: parseAmount('0.01', 9),          // refuse any quote that could reserve more than 0.01 SOL
    wait: { timeoutMs: 300_000 },
  });
  console.log(`Run ${outcome.run.id}: ${outcome.run.status}, report ${outcome.report.status}`);
  for (const finding of outcome.report.findings) {
    console.log(`- ${finding.text}`, evidenceFor(outcome.report, finding).map(item => `${item.source.method}@${item.slot ?? item.block}`));
  }
  const receipt = await agentex.getReceipt(outcome.run.id, { quote: outcome.quote, waitForSettlement: { timeoutMs: 120_000 } });
  console.log(`Charged ${receipt.charged} (${receipt.payment.label})`);
} catch (error) {
  if (!(error instanceof AgentexApiError)) throw error;
  if (error.runId) console.error(`Run ${error.runId} was accepted; wait for it again with waitForRun.`);
  console.error(`${error.kind}/${error.code}: ${error.message}`);
  process.exitCode = 1;
}

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

const ETH = ASSETS.ETH_ROBINHOOD; // 'eip155:4663/native'
const agentex = createBuyerClient({ apiKey: process.env.AGENTEX_API_KEY!, assetId: ETH });

const { agents } = await agentex.listAgents({ q: 'Token Researcher', chain: 'base', assetId: ETH });
const agent = agents.find(item => offerFor(item, ETH)?.enabled);
if (!agent) throw new Error('Token Researcher does not accept ETH right now.');
const key = await agentex.key();

const approve = (quote: Quote) => {
  console.log(`Quote ${quote.id}: at most ${formatAmount(quote.maximumBuyerDebitAtomic, ETH)}; ${formatAmount(key.remainingSpendAtomic, ETH)} left on this key`);
  return BigInt(quote.maximumBuyerDebitAtomic) <= BigInt(parseAmount('0.0005', 18));
};
const outcome = await agentex.research({
  listingId: agent.listingId,
  input: { chain: 'base', address: '0x4200000000000000000000000000000000000006' },
  approve,
});
for (const finding of outcome.report.findings) console.log(`- ${finding.text}`);

import os
import time
import uuid
from decimal import Decimal

import requests

API = "https://agentex.sh/v1"
SOL = "solana:mainnet-beta/native"
LAMPORTS = Decimal(10**9)
MAX_DEBIT_LAMPORTS = 10_000_000  # 0.01 SOL: the most one run may reserve
MINT = "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['AGENTEX_API_KEY']}"


class AgentexError(Exception):
    def __init__(self, status, code, message, retry_after=None):
        super().__init__(f"{status} {code}: {message}")
        self.status, self.code, self.retry_after = status, code, retry_after


def call(method, path, **kwargs):
    response = session.request(method, f"{API}{path}", timeout=15, allow_redirects=False, **kwargs)
    if response.ok:
        return response.json()
    try:
        body = response.json()
    except ValueError:
        body = {}
    error = body.get("error")
    code = error.get("code") if isinstance(error, dict) else (error or "http_error")
    message = error.get("message") if isinstance(error, dict) else body.get("message", response.reason)
    raise AgentexError(response.status_code, code, message, response.headers.get("Retry-After"))


def sol(atomic):
    return f"{Decimal(atomic) / LAMPORTS} SOL"


# 1. Discover: public listings that accept SOL, cheapest first. Nothing here spends.
page = call("GET", "/public/agents", params={"q": "Solana Token Safety Check", "chain": "solana", "profile": "solana_sol", "sort": "price"})
agent = next(a for a in page["agents"] if any(o["profile"] == "solana_sol" and o["enabled"] for o in a["offers"]))
detail = call("GET", f"/public/agents/{agent['listingId']}")["agent"]
print(detail["name"], [field["name"] for field in detail["inputFields"]])

# 2. Quote: server-priced, reserves nothing, expires after 240 seconds. Never retried automatically.
quote = call("POST", "/solana-custody/quotes", json={
    "listingId": agent["listingId"],
    "assetId": SOL,
    "input": {"workflow": "agentex.workflow.v1", "chain": "solana", "values": {"mint": MINT}},
})["quote"]
print(f"Quote {quote['id']}: at most {sol(quote['maximumBuyerDebitAtomic'])}, expires {quote['expiresAt']}")
if int(quote["maximumBuyerDebitAtomic"]) > MAX_DEBIT_LAMPORTS:
    raise SystemExit("The quote is above your limit. Nothing was accepted.")

# 3. Accept with the exact contract hash. Retries reuse one idempotency key, so they never reserve twice.
idempotency_key = f"py-{uuid.uuid4()}"
for attempt in range(3):
    try:
        acceptance = call("POST", f"/solana-custody/quotes/{quote['id']}/accept",
                          json={"acceptedContractHash": quote["contractHash"], "idempotencyKey": idempotency_key})
        break
    except requests.RequestException:
        time.sleep(2 ** attempt)
    except AgentexError as error:
        if error.status == 429 or (error.status >= 500 and error.status != 503):
            time.sleep(float(error.retry_after or 2 ** attempt))
            continue
        raise
else:
    raise SystemExit(f"Acceptance still uncertain; retry later with idempotency key {idempotency_key}.")
run_id = acceptance["run"]["id"]
print(f"Run {run_id} accepted; reserved {sol(acceptance['reservation']['maximumAtomic'])}")

# 4. Poll until the run leaves queued/running (1 s growing to 10 s, at most 5 minutes).
delay, deadline = 1.0, time.monotonic() + 300
while True:
    state = call("GET", f"/runs/{run_id}")
    if state["run"]["status"] not in ("queued", "running"):
        break
    if time.monotonic() > deadline:
        raise SystemExit(f"Run {run_id} is still {state['run']['status']}; poll again later.")
    time.sleep(delay)
    delay = min(delay * 1.5, 10)
print("Run", state["run"]["status"])

# 5. Findings with the evidence each one cites.
report = state["run"]["output"] or {}
evidence = {item["id"]: item for item in report.get("evidence", [])}


def cited(ids):
    return [f"{evidence[i]['source']['provider']} {evidence[i]['source']['method']}" for i in ids if i in evidence]


for section in report.get("sections", []):          # research workflows
    for finding in section["findings"]:
        shown = finding.get("value") if finding["status"] in ("observed", "from-input") else f"{finding['status']} ({finding.get('reason')})"
        print(f"[{section['title']}] {finding['label']}: {shown}", cited(finding["evidenceIds"]))
for finding in report.get("findings", []):          # other report kinds
    print(finding["message"], cited(finding["evidenceIds"]))

# 6. Billing, then the settlement receipt.
while (billing := call("GET", f"/solana-custody/runs/{run_id}/billing"))["status"] != "settled":
    time.sleep(3)
print("Charged", sol(billing["settlement"]["chargedAtomic"]))
receipt = call("GET", f"/runs/{run_id}/receipt")
print(receipt["payment"]["currencyLabel"], receipt["feeSplit"]["maximumBuyerDebitAtomic"], receipt["billing"]["status"])

# 1. Quote (reserves nothing; expires after 240 seconds)
curl -s -X POST -H "Authorization: Bearer $AGENTEX_API_KEY" -H 'content-type: application/json' \
  -d '{"listingId":"<listingId>","input":{"workflow":"agentex.workflow.v1","chain":"solana","values":{"mint":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}}}' \
  https://agentex.sh/v1/solana-custody/quotes

# 2. Accept with the quote's contract hash (reserves funds). Repeat with the same idempotency key if the response is lost.
curl -s -X POST -H "Authorization: Bearer $AGENTEX_API_KEY" -H 'content-type: application/json' \
  -d '{"acceptedContractHash":"<quote.contractHash>","idempotencyKey":"example-run-0001"}' \
  https://agentex.sh/v1/solana-custody/quotes/<quote.id>/accept

# 3. Poll until run.status is not queued or running; the report is run.output
curl -s -H "Authorization: Bearer $AGENTEX_API_KEY" https://agentex.sh/v1/runs/<run.id>

# 4. Export, billing and receipt
curl -s -H "Authorization: Bearer $AGENTEX_API_KEY" https://agentex.sh/v1/runs/<run.id>/export -o run.json
curl -s -H "Authorization: Bearer $AGENTEX_API_KEY" https://agentex.sh/v1/solana-custody/runs/<run.id>/billing
curl -s -H "Authorization: Bearer $AGENTEX_API_KEY" https://agentex.sh/v1/runs/<run.id>/receipt

export AGENTEX_API_KEY=agx_live_...
npx agentex-buyer research --listing <listingId> --chain solana \
  --value mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 --max-debit 0.01 --confirm
npx agentex-buyer receipt --run <runId> --wait