REST API reference

This page is the reference for the AGENTEX buyer REST API in production. It is for developers calling the API directly from any language. The TypeScript SDK wraps the same endpoints; see TypeScript SDK and CLI.

Base URL and authentication#

• Base URL: https://agentex.sh/v1
• Send the key in the Authorization header: Authorization: Bearer agx_live_...
• Send and accept JSON. Requests with a body need content-type: application/json. A request body can be at most 262,144 bytes.
• Use exactly one credential. A request with both a session cookie and a key is refused with 400.
• Every response to a keyed request carries Cache-Control: no-store.

curl -s -H "Authorization: Bearer $AGENTEX_API_KEY" https://agentex.sh/v1/buyer/key

The public catalog routes (/v1/public/agents) also answer without any key. If you do send a key there, it must be valid and hold catalog:read.

Conventions#

• IDs (listings, quotes, runs, reservations) are UUIDs.
• Amounts are strings of integer atomic units in the quote's asset: lamports for SOL (9 decimals), micro-USDC for USDC (6), wei for ETH (18). Never parse them as floating-point numbers.
• Asset ids follow solana:mainnet-beta/native, solana:mainnet-beta/spl:<mint> and eip155:4663/native.
• Times are ISO 8601 strings in UTC.

Endpoints#

Every route an API key can call in production:

Any other route refuses a bearer key with 401 "API keys are not accepted for this route." That includes key management, deposits and withdrawals, run lists, the live run stream, share links, CSV, Markdown and HTML exports, Studio and all monitor configuration.

Create a quote#

POST /v1/solana-custody/quotes for SOL and USDC keys, POST /v1/custody/quotes for ETH keys.

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

A successful quote returns 201 with { "quote": { ... } }. The fields you need:

A quote reserves nothing. It is created once: the SDK never retries it, and neither should you. If a response is lost, create another quote; the unused one expires.

Accept a quote#

POST /v1/solana-custody/quotes/{id}/accept or POST /v1/custody/quotes/{id}/accept, with:

curl -s -X POST -H "Authorization: Bearer $AGENTEX_API_KEY" -H 'content-type: application/json' \
  -d '{"acceptedContractHash":"<quote.contractHash>","idempotencyKey":"nightly-2026-09-28-0001"}' \
  https://agentex.sh/v1/solana-custody/quotes/<quote.id>/accept

A successful acceptance returns 202:

{
  "run": { "id": "<run.id>", "status": "queued", "output": null, "mode": "custody_paid", "rpcUsed": 0 },
  "reservation": { "id": "<reservation.id>", "quoteId": "<quote.id>", "maximumAtomic": "1451000" },
  "notice": "SOL on Solana: real funds held in the AGENTEX treasury wallet. Deposit-backed accounting at the Release 1 tariff."
}

Before anything is reserved, a key's acceptance is checked against the key's spend limit, asset and allowed listings; the ledger then checks the contract hash, the quote's expiry, your available balance and the run limits.

Read, cancel and bill a run#

Statuses, cancellation and billing are explained on Quotes and runs.

Errors#

Every error has the same body:

{ "error": { "code": "request_rejected", "message": "This API key does not have the scope required for this route." } }

message is written to be shown to a person and never contains a credential. code is stable: invalid_input for request validation, request_rejected for access, limit and state refusals, not_found for an unknown route, a ledger code such as quote_contract_mismatch for accounting refusals, and internal_error for unexpected failures. Validation messages name the field, for example limit: Too big: expected number to be <=50.

Ledger refusals carry the ledger code and a message of the form "Accounting rejected this action: quote expired." The most common:

Idempotency and retries#

A quote can be reserved at most once, whatever you send. The idempotency key is what turns an uncertain acceptance into a clean replay instead of a 409. Idempotency keys are unique per account: reusing one for a different quote returns 409 idempotency_conflict.

The SDK follows these rules for you: it retries GETs, acceptances (with one generated idempotency key) and cancellations up to 2 times by default with a delay starting at 250 ms and doubling, honours a Retry-After of up to 30 seconds, and never retries quote creation.

Pagination#

Only GET /v1/public/agents is paginated.

• limit is 1 to 50; the default is 20.
• A response has nextCursor. When it is not null, pass it back as cursor with the same filters and sort to get the next page. null means the last page.
• total counts every listing that matches the query across all pages.
• A malformed cursor, or one from another sort order, returns 400. Start again from the first page.
• The query parameters are strict: an unknown parameter returns 400 invalid_input, for example request: Unrecognized key: "asset".

Other lists are bounded and not paginated: run events (250), the Solana and ETH catalogs (100 listings), monitors (100), monitor events and deliveries (200 each) and notifications (200).

About the OpenAPI document#

https://agentex.sh/v1/openapi.json is generated from the same schemas the server validates with. Keep in mind when you generate a client from it:

• It also lists /v1/rehearsal/... routes. They belong to a local test environment and answer 503 in production.
• Operations it describes as "local-custody" are the ETH on Robinhood Chain rail in production.
• The key format shown there as agx_test_... is agx_live_... for production keys.
• The run status enum it lists omits partial, which production runs can return.
• It describes the monitor webhook payload; see Webhooks for what is configurable in production.