{"openapi":"3.1.0","info":{"title":"AGENTEX Buyer API","version":"1.2.0-local","description":"Buyer API for local rehearsal, ETH custody and the Solana rail (SOL and USDC keys belong to Solana accounts, and each key is bound to one asset). Accepting a quote requires its exact server contract hash; an API key never replaces that consent."},"servers":[{"url":"https://agentex.sh"}],"paths":{"/v1/buyer/key":{"get":{"operationId":"getBuyerKey","summary":"Read this key's own scopes, limits and remaining spend","security":[{"bearerApiKey":[]}],"x-agentex-scope":null,"responses":{"200":{"description":"Key grant and budget","content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"$ref":"#/components/schemas/ApiKeySelf"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/public/agents":{"get":{"operationId":"getPublicAgents","summary":"Search public agents (cursor pagination)","security":[{"bearerApiKey":["catalog:read"]}],"x-agentex-scope":"catalog:read","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100}},{"name":"chain","in":"query","required":false,"schema":{"type":"string","enum":["ethereum","base","robinhood","solana"]}},{"name":"ownership","in":"query","required":false,"schema":{"type":"string","enum":["first-party","independent"]}},{"name":"review","in":"query","required":false,"schema":{"default":"any","type":"string","enum":["reviewed","any"]}},{"name":"profile","in":"query","required":false,"schema":{"type":"string","enum":["sim","local_custody","solana_sol","solana_usdc"]}},{"name":"available","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["token_research","transaction_inspection","monitoring","custom_workflow","deployer_investigation","wallet_analysis"]}},{"name":"priceStructure","in":"query","required":false,"schema":{"type":"string","enum":["per_run","per_monitoring_window"]}},{"name":"permission","in":"query","required":false,"schema":{"type":"string","enum":["read_only","proposes_transactions","sends_notifications"]}},{"name":"topic","in":"query","required":false,"schema":{"type":"string","enum":["token-intelligence","contract-forensics","wallet-intelligence","transaction-safety","monitoring","defi","liquidity","lending-yield","staking","stablecoins","governance","treasuries","rwa","bridges","chain-activity","launches","nfts","security"]}},{"name":"sort","in":"query","required":false,"schema":{"default":"newest","type":"string","enum":["newest","name","price"]}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":600}}],"responses":{"200":{"description":"One page of public agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/public/agents/{listingId}":{"get":{"operationId":"getPublicAgentsListingId","summary":"Read a public agent: permissions, limits, price, limitations","security":[{"bearerApiKey":["catalog:read"]}],"x-agentex-scope":"catalog:read","parameters":[{"name":"listingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Public agent detail","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/AgentDetail"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/rehearsal/catalog":{"get":{"operationId":"getRehearsalCatalog","summary":"List SIM rehearsal listings","security":[{"bearerApiKey":["catalog:read"]}],"x-agentex-scope":"catalog:read","x-agentex-profile":"sim","responses":{"200":{"description":"Listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/custody/catalog":{"get":{"operationId":"getCustodyCatalog","summary":"List local-custody listings","security":[{"bearerApiKey":["catalog:read"]}],"x-agentex-scope":"catalog:read","x-agentex-profile":"local_custody","responses":{"200":{"description":"Listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/rehearsal/quotes":{"post":{"operationId":"postRehearsalQuotes","summary":"Create a SIM quote","security":[{"bearerApiKey":["quotes:write"]}],"x-agentex-scope":"quotes:write","x-agentex-profile":"sim","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"listingId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"input":{"type":"object","properties":{"chain":{"type":"string","enum":["ethereum","base","robinhood"]},"address":{"type":"string"},"scope":{"default":"metadata-and-controls","type":"string","const":"metadata-and-controls"},"snapshotBlock":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"}},"required":["chain","address"],"additionalProperties":false},"resultPolicy":{"default":"complete_only","type":"string","enum":["complete_only","canonical_metadata"]}},"required":["listingId","input"],"additionalProperties":false}}}},"responses":{"201":{"description":"Server-priced quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/rehearsal/quotes/{id}/accept":{"post":{"operationId":"postRehearsalQuotesIdAccept","summary":"Accept a SIM quote by its contract hash","security":[{"bearerApiKey":["quotes:write"]}],"x-agentex-scope":"quotes:write","x-agentex-profile":"sim","x-agentex-spend-limit":"Counts the quote maximumBuyerDebitAtomic against the key spend limit before reservation.","x-agentex-idempotency":"Body idempotencyKey; a retry with the same key and body returns the original result.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"acceptedContractHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["acceptedContractHash","idempotencyKey"],"additionalProperties":false}}}},"responses":{"202":{"description":"Reserved and queued, or the original acceptance on idempotent retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acceptance"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/custody/quotes":{"post":{"operationId":"postCustodyQuotes","summary":"Create a local-custody quote","security":[{"bearerApiKey":["quotes:write"]}],"x-agentex-scope":"quotes:write","x-agentex-profile":"local_custody","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"listingId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"input":{"type":"object","properties":{"chain":{"type":"string","enum":["ethereum","base","robinhood"]},"address":{"type":"string"},"scope":{"default":"metadata-and-controls","type":"string","const":"metadata-and-controls"},"snapshotBlock":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"}},"required":["chain","address"],"additionalProperties":false},"resultPolicy":{"default":"complete_only","type":"string","enum":["complete_only","canonical_metadata"]}},"required":["listingId","input"],"additionalProperties":false}}}},"responses":{"201":{"description":"Server-priced quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/custody/quotes/{id}/accept":{"post":{"operationId":"postCustodyQuotesIdAccept","summary":"Accept a local-custody quote by its contract hash","security":[{"bearerApiKey":["quotes:write"]}],"x-agentex-scope":"quotes:write","x-agentex-profile":"local_custody","x-agentex-spend-limit":"Counts the quote maximumBuyerDebitAtomic against the key spend limit before reservation.","x-agentex-idempotency":"Body idempotencyKey; a retry with the same key and body returns the original result.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"acceptedContractHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["acceptedContractHash","idempotencyKey"],"additionalProperties":false}}}},"responses":{"202":{"description":"Reserved and queued, or the original acceptance on idempotent retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acceptance"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/runs/{id}":{"get":{"operationId":"getRunsId","summary":"Read run status and events","security":[{"bearerApiKey":["runs:read"]}],"x-agentex-scope":"runs:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Run status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStatus"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/runs/{id}/cancel":{"post":{"operationId":"postRunsIdCancel","summary":"Cancel a paid run","security":[{"bearerApiKey":["runs:cancel"]}],"x-agentex-scope":"runs:cancel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cancelled run, or the unchanged run if it already ended","content":{"application/json":{"schema":{"type":"object","required":["run"],"properties":{"run":{"$ref":"#/components/schemas/Run"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/runs/{id}/export":{"get":{"operationId":"getRunsIdExport","summary":"Download the run result export","security":[{"bearerApiKey":["runs:read"]}],"x-agentex-scope":"runs:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Export download","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunExport"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/runs/{id}/receipt":{"get":{"operationId":"getRunsIdReceipt","summary":"Download the settlement receipt of a paid run: its payment currency and exact amounts","security":[{"bearerApiKey":["billing:read"]}],"x-agentex-scope":"billing:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Receipt download","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Settlement receipt: quote, fee split, settlement and payment currency (payment.assetId, payment.currencyLabel)."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/rehearsal/runs/{id}/billing":{"get":{"operationId":"getRehearsalRunsIdBilling","summary":"Read SIM run billing","security":[{"bearerApiKey":["billing:read"]}],"x-agentex-scope":"billing:read","x-agentex-profile":"sim","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Billing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Billing"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/custody/runs/{id}/billing":{"get":{"operationId":"getCustodyRunsIdBilling","summary":"Read local-custody run billing","security":[{"bearerApiKey":["billing:read"]}],"x-agentex-scope":"billing:read","x-agentex-profile":"local_custody","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Billing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Billing"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/solana-custody/catalog":{"get":{"operationId":"getSolana-custodyCatalog","summary":"List listings priced in the key's Solana asset (SOL or USDC)","security":[{"bearerApiKey":["catalog:read"]}],"x-agentex-scope":"catalog:read","x-agentex-profile":["solana_sol","solana_usdc"],"parameters":[{"name":"assetId","in":"query","required":false,"schema":{"type":"string","description":"Optional; a key always reads its own asset and another asset is refused."}}],"responses":{"200":{"description":"Listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/solana-custody/quotes":{"post":{"operationId":"postSolana-custodyQuotes","summary":"Create a SOL or USDC quote for a listing in the key's asset","security":[{"bearerApiKey":["quotes:write"]}],"x-agentex-scope":"quotes:write","x-agentex-profile":["solana_sol","solana_usdc"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"listingId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"input":{"type":"object","properties":{"chain":{"type":"string","enum":["ethereum","base","robinhood"]},"address":{"type":"string"},"scope":{"default":"metadata-and-controls","type":"string","const":"metadata-and-controls"},"snapshotBlock":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"}},"required":["chain","address"],"additionalProperties":false},"resultPolicy":{"default":"complete_only","type":"string","enum":["complete_only","canonical_metadata"]},"assetId":{"description":"SOL or USDC asset id; SOL when omitted on a listing that accepts both. A key stays on its own asset.","type":"string","minLength":1,"maxLength":200}},"required":["listingId","input"],"additionalProperties":false}}}},"responses":{"201":{"description":"Server-priced quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/solana-custody/quotes/{id}/accept":{"post":{"operationId":"postSolana-custodyQuotesIdAccept","summary":"Accept a SOL or USDC quote by its contract hash","security":[{"bearerApiKey":["quotes:write"]}],"x-agentex-scope":"quotes:write","x-agentex-profile":["solana_sol","solana_usdc"],"x-agentex-spend-limit":"Counts the quote maximumBuyerDebitAtomic against the key spend limit before reservation.","x-agentex-idempotency":"Body idempotencyKey; a retry with the same key and body returns the original result.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"acceptedContractHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["acceptedContractHash","idempotencyKey"],"additionalProperties":false}}}},"responses":{"202":{"description":"Reserved and queued, or the original acceptance on idempotent retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acceptance"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/solana-custody/runs/{id}/billing":{"get":{"operationId":"getSolana-custodyRunsIdBilling","summary":"Read SOL or USDC run billing","security":[{"bearerApiKey":["billing:read"]}],"x-agentex-scope":"billing:read","x-agentex-profile":["solana_sol","solana_usdc"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Billing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Billing"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/monitors":{"get":{"operationId":"getMonitors","summary":"List your monitors","security":[{"bearerApiKey":["monitors:read"]}],"x-agentex-scope":"monitors:read","responses":{"200":{"description":"Monitors, newest first","content":{"application/json":{"schema":{"type":"object","required":["monitors"],"properties":{"monitors":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Monitor"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"postMonitors","summary":"Create an unpaid monitor on your own Watchtower version (prepaid monitors need a session)","security":[{"bearerApiKey":["monitors:write"]}],"x-agentex-scope":"monitors:write","x-agentex-key-restriction":"With an API key, paymentProfile must be omitted or \"none\" and spendCapAtomic omitted (403 otherwise).","x-agentex-idempotency":"Body idempotencyKey; a retry with the same key and body returns the original result.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"versionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"listingId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"triggers":{"default":[],"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"onRule":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"action":{"type":"string","enum":["token-authority-check","sender-approvals-check"]},"lookbackBlocks":{"default":100,"type":"integer","minimum":0,"maximum":1999},"maximumRuns":{"default":5,"type":"integer","minimum":1,"maximum":50}},"required":["id","onRule","action"],"additionalProperties":false}},"name":{"type":"string","minLength":1,"maxLength":100},"chain":{"type":"string","enum":["ethereum","base","robinhood"]},"rules":{"minItems":1,"maxItems":8,"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"type":{"type":"string","const":"erc20-transfer"},"token":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"minimumAtomic":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"}},"required":["id","type","token"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"type":{"type":"string","const":"erc20-approval"},"token":{"type":"string"},"owner":{"type":"string"},"spender":{"type":"string"}},"required":["id","type","token","owner"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"type":{"type":"string","const":"authority-change"},"contract":{"type":"string"},"events":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"string","enum":["Upgraded","AdminChanged","BeaconUpgraded","OwnershipTransferred"]}}},"required":["id","type","contract"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"type":{"type":"string","const":"wallet-token-flow"},"wallet":{"type":"string"},"tokens":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string"}},"direction":{"type":"string","enum":["in","out"]}},"required":["id","type","wallet","tokens","direction"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"type":{"type":"string","const":"pool-activity"},"pool":{"type":"string"},"dex":{"type":"string","enum":["uniswap-v2","uniswap-v3","aerodrome"]},"events":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["Swap","Mint","Burn"]}},"minimumAmount0Atomic":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"minimumAmount1Atomic":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"}},"required":["id","type","pool","dex"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"type":{"type":"string","const":"governance-change"},"contract":{"type":"string"},"events":{"minItems":1,"maxItems":14,"type":"array","items":{"type":"string","enum":["ProposalCreated","ProposalQueued","ProposalExecuted","ProposalCanceled","CallScheduled","CallExecuted","Cancelled","MinDelayChange","QueueTransaction","ExecuteTransaction","CancelTransaction","NewDelay","NewAdmin","NewPendingAdmin"]}}},"required":["id","type","contract"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"type":{"type":"string","const":"control-change"},"contract":{"type":"string"},"events":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["RoleGranted","RoleRevoked","RoleAdminChanged","Paused","Unpaused"]}}},"required":["id","type","contract"],"additionalProperties":false}]}},"windowBlocks":{"default":25,"type":"integer","minimum":1,"maximum":2000},"maximumLogs":{"default":50,"type":"integer","minimum":1,"maximum":100},"durationSeconds":{"type":"integer","minimum":60,"maximum":2592000},"tickBudget":{"type":"integer","minimum":1,"maximum":10000},"rpcBudget":{"type":"integer","minimum":10,"maximum":100000},"startBlock":{"type":"string","pattern":"^(0|[1-9][0-9]{0,15})$"},"webhookUrl":{"type":"string","maxLength":500},"paymentProfile":{"default":"none","type":"string","enum":["none","sim","local_custody"]},"spendCapAtomic":{"type":"string","pattern":"^[1-9][0-9]{0,77}$"},"consentHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["name","chain","rules","durationSeconds","tickBudget","rpcBudget","idempotencyKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"Idempotent replay; webhookSecret is null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorCreated"}}}},"201":{"description":"Created; webhookSecret is shown only here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorCreated"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/monitors/{id}":{"get":{"operationId":"getMonitorsId","summary":"Read a monitor with windows, events and deliveries","security":[{"bearerApiKey":["monitors:read"]}],"x-agentex-scope":"monitors:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Monitor detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/monitors/{id}/stop":{"post":{"operationId":"postMonitorsIdStop","summary":"Stop a monitor immediately","security":[{"bearerApiKey":["monitors:write"]}],"x-agentex-scope":"monitors:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Stopped monitor","content":{"application/json":{"schema":{"type":"object","required":["monitor"],"properties":{"monitor":{"$ref":"#/components/schemas/Monitor"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/notifications":{"get":{"operationId":"getNotifications","summary":"List in-app monitor notifications","security":[{"bearerApiKey":["monitors:read"]}],"x-agentex-scope":"monitors:read","responses":{"200":{"description":"Notifications, newest first","content":{"application/json":{"schema":{"type":"object","required":["notifications"],"properties":{"notifications":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/Notification"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/notifications/{id}/ack":{"post":{"operationId":"postNotificationsIdAck","summary":"Acknowledge a notification","security":[{"bearerApiKey":["monitors:write"]}],"x-agentex-scope":"monitors:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Acknowledged notification","content":{"application/json":{"schema":{"type":"object","required":["notification"],"properties":{"notification":{"$ref":"#/components/schemas/Notification"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"webhooks":{"monitorEvent":{"post":{"summary":"Monitor event or retraction delivered to a monitor webhook","description":"Verify x-agentex-signature (v1=HMAC-SHA256 over `timestamp.deliveryId.body` with the webhook secret), reject timestamps older than 5 minutes and drop a repeated x-agentex-event-id before acting.","parameters":[{"name":"x-agentex-signature","in":"header","required":true,"schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"x-agentex-event-id","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Delivery ID; the replay-protection key."},{"name":"x-agentex-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,12}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"}}}},"responses":{"200":{"description":"Accepted by the receiver"}}}}},"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"agx_test_<43 base64url chars>","description":"Scoped API key (catalog:read, quotes:write, runs:read, runs:cancel, billing:read, monitors:read, monitors:write). Send exactly one credential: a request with both a session cookie and a bearer key is rejected."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ApiKeySelf":{"type":"object","required":["id","scopes","profile","spendLimitAtomic","spendUsedAtomic","remainingSpendAtomic","expiresAt","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string"},"last4":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["catalog:read","quotes:write","runs:read","runs:cancel","billing:read","monitors:read","monitors:write"]}},"profile":{"type":"string","enum":["sim","local_custody","solana_sol","solana_usdc"]},"assetId":{"type":"string"},"listingIds":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string","format":"uuid"}}]},"spendLimitAtomic":{"type":"string","pattern":"^(0|[1-9][0-9]*)$","description":"Integer amount in the asset atomic unit."},"spendUsedAtomic":{"type":"string","pattern":"^(0|[1-9][0-9]*)$","description":"Integer amount in the asset atomic unit."},"remainingSpendAtomic":{"type":"string","pattern":"^(0|[1-9][0-9]*)$","description":"Integer amount in the asset atomic unit."},"rateLimitPerMinute":{"type":"integer"},"requestsLast24h":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"lastUsedAt":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"revokedAt":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}]},"status":{"type":"string","enum":["active","expired","revoked"]}}},"AgentSummary":{"type":"object","additionalProperties":true,"description":"Public agent summary","properties":{"listingId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"chains":{"type":"array","items":{"type":"string"}},"offers":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Purchase offer per payment profile; pricing.maximumBuyerDebitAtomic is the per-run price cap","properties":{"profile":{"type":"string"},"enabled":{"type":"boolean"}}}},"availability":{"type":"object","additionalProperties":true,"description":"Availability","properties":{"available":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}}}}},"required":["listingId","name","offers"]},"AgentPage":{"type":"object","required":["agents","nextCursor"],"properties":{"agents":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/AgentSummary"}},"nextCursor":{"oneOf":[{"type":"null"},{"type":"string","maxLength":200}],"description":"Pass as `cursor` for the next page; null on the last page."},"environment":{"type":"object","additionalProperties":true,"description":"Environment notice","properties":{}}}},"AgentDetail":{"allOf":[{"$ref":"#/components/schemas/AgentSummary"},{"type":"object","additionalProperties":true,"description":"Detail","properties":{"permissions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Permission","properties":{"id":{"type":"string"},"label":{"type":"string"},"detail":{"type":"string"}}}},"limits":{"type":"object","additionalProperties":true,"description":"Execution limits","properties":{"maximumRpcCalls":{"type":"integer"},"maximumDurationMs":{"type":"integer"},"maximumOutputBytes":{"type":"integer"}}},"inputFields":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Input field","properties":{}}},"resultPolicies":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Result policy","properties":{}}},"refundPolicy":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}}}}]},"Catalog":{"type":"object","required":["listings"],"properties":{"listings":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":true,"description":"Listing with immutable manifest, tariffs, asset and result contracts","properties":{}}},"pricingPolicy":{"type":"object","additionalProperties":true,"description":"Pricing policy","properties":{}}}},"QuoteResponse":{"type":"object","required":["quote"],"properties":{"quote":{"type":"object","additionalProperties":true,"required":["id","contractHash","maximumBuyerDebitAtomic","expiresAt"],"properties":{"id":{"type":"string","format":"uuid"},"contractHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"maximumBuyerDebitAtomic":{"type":"string","pattern":"^(0|[1-9][0-9]*)$","description":"Integer amount in the asset atomic unit."},"expiresAt":{"type":"string","format":"date-time"}}}}},"Run":{"type":"object","additionalProperties":true,"required":["id","status"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"output":{"type":"object","additionalProperties":true,"description":"Result report when available","properties":{}},"error":{}}},"RunEvent":{"type":"object","required":["id","step","message","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"step":{"type":"string"},"message":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"RunStatus":{"type":"object","required":["run","events"],"properties":{"run":{"$ref":"#/components/schemas/Run"},"events":{"type":"array","maxItems":250,"items":{"$ref":"#/components/schemas/RunEvent"}}}},"RunExport":{"type":"object","required":["run","version","events"],"description":"Canonical JSON export. Header X-Agentex-Artifact-Id names the stored artifact.","properties":{"run":{"$ref":"#/components/schemas/Run"},"version":{"type":"object","additionalProperties":true,"description":"Immutable version","properties":{}},"events":{"type":"array","items":{"$ref":"#/components/schemas/RunEvent"}}}},"Acceptance":{"type":"object","required":["run","reservation","notice"],"properties":{"run":{"$ref":"#/components/schemas/Run"},"reservation":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"maximumAtomic":{"type":"string","pattern":"^(0|[1-9][0-9]*)$","description":"Integer amount in the asset atomic unit."}}},"notice":{"type":"string"}}},"Billing":{"type":"object","additionalProperties":true,"required":["runId","status"],"properties":{"runId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["reserved","pending","settled"]},"settlement":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":true,"properties":{"chargedAtomic":{"type":"string","pattern":"^(0|[1-9][0-9]*)$","description":"Integer amount in the asset atomic unit."}}}]}}},"Monitor":{"type":"object","additionalProperties":true,"required":["id","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"versionId":{"type":"string","format":"uuid"},"chain":{"type":"string"},"status":{"type":"string","enum":["active","paused","stopped","expired","exhausted"]},"statusReason":{"type":["string","null"]},"endsAt":{"type":"string","format":"date-time"},"tickBudget":{"type":"integer"},"ticksUsed":{"type":"integer"},"rpcBudget":{"type":"integer"},"rpcUsed":{"type":"integer"},"webhook":{"oneOf":[{"type":"null"},{"type":"object","properties":{"url":{"type":"string"},"signature":{"type":"string"}}}]}}},"MonitorCreated":{"type":"object","required":["monitor","webhookSecret","replayed"],"properties":{"monitor":{"$ref":"#/components/schemas/Monitor"},"webhookSecret":{"oneOf":[{"type":"null"},{"type":"string"}]},"replayed":{"type":"boolean"}}},"MonitorDetail":{"type":"object","required":["monitor","windows","events","deliveries"],"properties":{"monitor":{"$ref":"#/components/schemas/Monitor"},"windows":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Window","properties":{}}},"missedWindows":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Window","properties":{}}},"events":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Event","properties":{}}},"retractedEvents":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Event","properties":{}}},"deliveries":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Delivery log entry","properties":{}}}}},"Notification":{"type":"object","required":["id","monitorId","kind","title","body","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"monitorId":{"type":"string","format":"uuid"},"kind":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"event":{"type":"object","additionalProperties":true,"description":"Event payload","properties":{}},"createdAt":{"type":"string","format":"date-time"},"acknowledgedAt":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}]}}},"WebhookPayload":{"type":"object","additionalProperties":true,"description":"Monitor webhook body","properties":{"type":{"type":"string","enum":["monitor.event","monitor.event.retracted"]},"eventId":{"type":"string","format":"uuid"},"monitorId":{"type":"string","format":"uuid"},"chain":{"type":"string"},"ruleId":{"type":"string"},"blockNumber":{"type":"string"},"blockHash":{"type":"string"},"transactionHash":{"type":"string"},"logIndex":{"type":"integer"},"status":{"type":"string","enum":["active","retracted"]},"observedAt":{"type":"string","format":"date-time"}},"required":["type","eventId","monitorId"]}},"responses":{"BadRequest":{"description":"Invalid input, or both a session and a bearer key were sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, unknown, malformed, expired or revoked key (identical response for each)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Scope, profile, listing restriction or key spend limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found or not visible to this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Ledger or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Per-key, per-client or queue limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Profile or research provider disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"x-agentex-limits":{"keyMaximumDays":90,"keyRateLimitPerMinute":"1-600, default 60","clientRateLimitPerMinute":120,"quoteCreateRateLimitPerMinute":10,"monitorCreateRateLimitPerMinute":10,"activeRunsPerBuyer":3,"dailyRunsPerBuyer":20,"activeMonitorsPerOwner":5,"requestBodyBytes":262144,"quoteTtlSeconds":240,"catalogPageSize":"1-50, default 20","idempotencyKey":"8-128 characters [a-zA-Z0-9_-]; reuse the same key after an uncertain acceptance or monitor creation"}}