Marketplace
Read-only discovery of the Virtuals ACP agent marketplace. Proxies ACP's public (unauthenticated) API; moves no money and holds no Virtuals credential. Search is semantic - pin walletAddress, never a name.
The ACP marketplace leaderboard (top agents by volume), cursor-paginated
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Query Parameters
Opaque pagination cursor from the previous page's pageInfo.nextCursor.
251 <= value <= 100Response Body
application/json
application/json
curl -X GET "https://api.app.botanary.xyz/marketplace/agents"{
"agents": [
{
"walletAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"name": "string",
"description": "string",
"imageUrl": "string",
"rating": 0,
"offerings": [
{
"id": "string",
"name": "string",
"description": "string",
"priceUsd": 0,
"slaMinutes": 0,
"requiresFunds": true,
"requirementsSchema": null
}
],
"successRate": 0,
"totalJobs": 0,
"totalVolumeUsd": 0,
"totalRevenueUsd": 0,
"uniqueWallets": 0,
"recentVolumeUsd": [
{
"timestamp": "2019-08-24T14:15:22Z",
"value": 0
}
],
"chainIds": [
0
]
}
],
"nextCursor": "string",
"total": 0
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}Whether the shared Botanary evaluator is provisioned
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Response Body
application/json
application/json
curl -X GET "https://api.app.botanary.xyz/marketplace/agents/evaluator"{
"connected": true,
"wallet": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}Semantic search of ACP agents (query required; there is no browse-all)
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Query Parameters
The task to search for, in words. Search is SEMANTIC, not a name lookup - never resolve an agent by name for anything that moves money; pin the returned walletAddress.
1 <= lengthComma-separated chain ids to filter by.
Maximum number of results.
1 <= valueResponse Body
application/json
application/json
application/json
curl -X GET "https://api.app.botanary.xyz/marketplace/agents/search?query=string"[
{
"walletAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"name": "string",
"description": "string",
"imageUrl": "string",
"rating": 0,
"offerings": [
{
"id": "string",
"name": "string",
"description": "string",
"priceUsd": 0,
"slaMinutes": 0,
"requiresFunds": true,
"requirementsSchema": null
}
],
"successRate": 0,
"totalJobs": 0,
"totalVolumeUsd": 0,
"totalRevenueUsd": 0,
"uniqueWallets": 0,
"recentVolumeUsd": [
{
"timestamp": "2019-08-24T14:15:22Z",
"value": 0
}
],
"chainIds": [
0
]
}
]{
"error": {
"code": "out_of_scope",
"message": "This action exceeds the per-action cap.",
"declineReason": "cap_exceeded",
"details": {},
"requestId": "string"
}
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}Full record for one ACP agent, pinned by wallet address
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Path Parameters
The agent's on-chain wallet address (the only safe identity for money).
^0x[a-fA-F0-9]{40}$Response Body
application/json
application/json
application/json
curl -X GET "https://api.app.botanary.xyz/marketplace/agents/0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"{
"walletAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"name": "string",
"description": "string",
"imageUrl": "string",
"rating": 0,
"offerings": [
{
"id": "string",
"name": "string",
"description": "string",
"priceUsd": 0,
"slaMinutes": 0,
"requiresFunds": true,
"requirementsSchema": null
}
],
"successRate": 0,
"totalJobs": 0,
"totalVolumeUsd": 0,
"totalRevenueUsd": 0,
"uniqueWallets": 0,
"recentVolumeUsd": [
{
"timestamp": "2019-08-24T14:15:22Z",
"value": 0
}
],
"chainIds": [
0
]
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}{
"error": {
"code": "out_of_scope",
"message": "This action exceeds the per-action cap.",
"declineReason": "cap_exceeded",
"details": {},
"requestId": "string"
}
}Build a bounded mandate to hire one ACP agent (unsigned; sign client-side)
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.app.botanary.xyz/marketplace/agents/hire/build" \ -H "Content-Type: application/json" \ -d '{ "agentWallet": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0", "chainId": 0, "perJobBudget": 0, "delegateeAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0" }'{
"mandateId": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
"account": {
"id": "acct_01H8",
"label": "Main account",
"address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"type": "Smart account",
"deploymentStatus": "counterfactual",
"chainId": 42161,
"signerAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"frozen": true,
"index": 0,
"hidden": true,
"purpose": "primary",
"createdAt": "2019-08-24T14:15:22Z",
"totalFiat": 8765.66
},
"policySummary": "This agent may call Router, pay Treasury, max 50 USDC per call. Expires on 2027-01-01. Revoking the mandate stops it immediately.",
"enableUserOp": {
"sender": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"nonce": "0",
"factory": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"factoryData": "0x",
"callData": "0x",
"callGasLimit": "200000",
"verificationGasLimit": "150000",
"preVerificationGas": "50000",
"maxFeePerGas": "1000000000",
"maxPriorityFeePerGas": "1000000000",
"paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"paymasterVerificationGasLimit": "string",
"paymasterPostOpGasLimit": "string",
"paymasterData": "0x",
"signature": "0x",
"entryPoint": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"chainId": 42161
},
"userOpHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
"simulation": {
"id": "string",
"intentType": "send",
"willSucceed": true,
"declineReason": "cap_exceeded",
"amountIn": {
"token": {
"symbol": "USDC",
"chainId": 42161,
"address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
},
"amount": 50
},
"amountOut": {
"token": {
"symbol": "USDC",
"chainId": 42161,
"address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
},
"amount": 50
},
"rate": 1.08,
"route": "USDC → EURC via Uniswap v3",
"slippageBps": 30,
"fees": [
{
"token": {
"symbol": "USDC",
"chainId": 42161,
"address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
},
"amount": 50
}
],
"gas": {
"method": "sponsored",
"cost": {
"token": {
"symbol": "USDC",
"chainId": 42161,
"address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
},
"amount": 50
},
"sponsored": true
},
"warnings": [
"string"
],
"expiresAt": "2019-08-24T14:15:22Z"
}
}{
"error": {
"code": "out_of_scope",
"message": "This action exceeds the per-action cap.",
"declineReason": "cap_exceeded",
"details": {},
"requestId": "string"
}
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}{
"error": {
"code": "out_of_scope",
"message": "This action exceeds the per-action cap.",
"declineReason": "per_action_exceeded"
}
}Subscription-scoped SSE stream of live agent leaderboard stats - read-only, no auth
Query Parameters
Comma-separated agent wallet addresses to subscribe to, e.g. '0xabc...,0xdef...'.
Response Body
text/event-stream
curl -X GET "https://api.app.botanary.xyz/marketplace/agents/stream"{
"walletAddress": "string",
"successRate": 0,
"totalJobs": 0,
"rating": 0,
"pricePerJobUsd": 0,
"totalVolumeUsd": 0,
"asOf": "2019-08-24T14:15:22Z"
}The caller's ACP jobs (My jobs), newest first
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Response Body
application/json
application/json
curl -X GET "https://api.app.botanary.xyz/marketplace/jobs"[
{
"jobId": "string",
"chainId": 0,
"agentName": "string",
"agentWallet": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"offering": "string",
"status": "requested",
"budgetUsd": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"refunded": true,
"deliverable": {
"title": "string",
"lines": [
"string"
],
"readByEvaluator": true
},
"events": [
{
"label": "string",
"actor": "you",
"at": "2019-08-24T14:15:22Z",
"txHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b"
}
]
}
]{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}One ACP job's full record (lifecycle + deliverable)
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Path Parameters
Response Body
application/json
application/json
application/json
curl -X GET "https://api.app.botanary.xyz/marketplace/jobs/0/string"{
"jobId": "string",
"chainId": 0,
"agentName": "string",
"agentWallet": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"offering": "string",
"status": "requested",
"budgetUsd": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"refunded": true,
"deliverable": {
"title": "string",
"lines": [
"string"
],
"readByEvaluator": true
},
"events": [
{
"label": "string",
"actor": "you",
"at": "2019-08-24T14:15:22Z",
"txHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b"
}
]
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}{
"error": {
"code": "out_of_scope",
"message": "This action exceeds the per-action cap.",
"declineReason": "cap_exceeded",
"details": {},
"requestId": "string"
}
}Build the unsigned createJob op for a hire (provider pinned by the mandate)
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://api.app.botanary.xyz/marketplace/jobs/create/build" \ -H "Content-Type: application/json" \ -d '{ "mandateId": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b", "agentWallet": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0", "description": "string", "chainId": 0 }'{
"userOp": {
"sender": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"nonce": "0",
"factory": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"factoryData": "0x",
"callData": "0x",
"callGasLimit": "200000",
"verificationGasLimit": "150000",
"preVerificationGas": "50000",
"maxFeePerGas": "1000000000",
"maxPriorityFeePerGas": "1000000000",
"paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"paymasterVerificationGasLimit": "string",
"paymasterPostOpGasLimit": "string",
"paymasterData": "0x",
"signature": "0x",
"entryPoint": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"chainId": 42161
},
"userOpHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b"
}{
"error": {
"code": "out_of_scope",
"message": "This action exceeds the per-action cap.",
"declineReason": "cap_exceeded",
"details": {},
"requestId": "string"
}
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}Build the unsigned approve+fund op for a hire (budget capped by the arg-gate)
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://api.app.botanary.xyz/marketplace/jobs/fund/build" \ -H "Content-Type: application/json" \ -d '{ "mandateId": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b", "jobId": "string", "perJobBudget": 0, "chainId": 0 }'{
"userOp": {
"sender": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"nonce": "0",
"factory": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"factoryData": "0x",
"callData": "0x",
"callGasLimit": "200000",
"verificationGasLimit": "150000",
"preVerificationGas": "50000",
"maxFeePerGas": "1000000000",
"maxPriorityFeePerGas": "1000000000",
"paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"paymasterVerificationGasLimit": "string",
"paymasterPostOpGasLimit": "string",
"paymasterData": "0x",
"signature": "0x",
"entryPoint": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"chainId": 42161
},
"userOpHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b"
}{
"error": {
"code": "out_of_scope",
"message": "This action exceeds the per-action cap.",
"declineReason": "cap_exceeded",
"details": {},
"requestId": "string"
}
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}Whether the caller has a connected Virtuals agent wallet (custodial mode)
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Response Body
application/json
application/json
curl -X GET "https://api.app.botanary.xyz/marketplace/managed/connection"{
"connected": true,
"walletAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}Start (or short-circuit) the device-code connect flow for the caller's own Virtuals agent
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Response Body
application/json
application/json
curl -X POST "https://api.app.botanary.xyz/marketplace/managed/connect"{
"loginUrl": "string",
"requestId": "string",
"alreadyConnected": true,
"walletAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}Poll whether the owner has approved the device-code login yet
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Query Parameters
Response Body
application/json
application/json
curl -X GET "https://api.app.botanary.xyz/marketplace/managed/connect/status?requestId=string"{
"connected": true,
"walletAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}Build an unsigned deposit from the owner's own account into their connected Virtuals wallet
Authorization
sessionToken Botanary session token from POST /auth/session. Not a key - a revocable session bearer.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://api.app.botanary.xyz/marketplace/managed/deposit/build" \ -H "Content-Type: application/json" \ -d '{ "chainId": 0, "amount": 0, "tokenSymbol": "string", "tokenAddress": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0" }'{
"intentType": "send",
"userOp": {
"sender": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"nonce": "0",
"factory": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"factoryData": "0x",
"callData": "0x",
"callGasLimit": "200000",
"verificationGasLimit": "150000",
"preVerificationGas": "50000",
"maxFeePerGas": "1000000000",
"maxPriorityFeePerGas": "1000000000",
"paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"paymasterVerificationGasLimit": "string",
"paymasterPostOpGasLimit": "string",
"paymasterData": "0x",
"signature": "0x",
"entryPoint": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"chainId": 42161
},
"userOpHash": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
"humanSummary": "string",
"simulation": {
"id": "string",
"intentType": "send",
"willSucceed": true,
"declineReason": "cap_exceeded",
"amountIn": {
"token": {
"symbol": "USDC",
"chainId": 42161,
"address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
},
"amount": 50
},
"amountOut": {
"token": {
"symbol": "USDC",
"chainId": 42161,
"address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
},
"amount": 50
},
"rate": 1.08,
"route": "USDC → EURC via Uniswap v3",
"slippageBps": 30,
"fees": [
{
"token": {
"symbol": "USDC",
"chainId": 42161,
"address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
},
"amount": 50
}
],
"gas": {
"method": "sponsored",
"cost": {
"token": {
"symbol": "USDC",
"chainId": 42161,
"address": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
},
"amount": 50
},
"sponsored": true
},
"warnings": [
"string"
],
"expiresAt": "2019-08-24T14:15:22Z"
},
"riskReducing": true,
"instant": true,
"gasless": true,
"gasPermit": {
"paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"tokenName": "USD Coin",
"tokenVersion": "2",
"kernelVersion": "0.3.3",
"permitAmount": "212142",
"permitNonce": "2",
"permitDeadline": "string",
"permitDigest": "0x4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b4c1f9a0b2d7e8c3f1a6b0d4e2c9f7a1b",
"signaturePrefix": "0x",
"estimatedFee": 0.031296
},
"usdtApproval": {
"token": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"paymaster": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"amount": "string",
"calls": [
{
"to": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0",
"data": "0x",
"value": "string"
}
]
},
"custodial": true,
"custodyLabel": "Custodial - not self-custodial",
"managedAgentWallet": "0x8f2A9c4419aD77b0392bC41D8123aa77c0Fe41D0"
}{
"error": {
"code": "out_of_scope",
"message": "This action exceeds the per-action cap.",
"declineReason": "cap_exceeded",
"details": {},
"requestId": "string"
}
}{
"error": {
"code": "unauthorized",
"message": "Session token missing or expired."
}
}Market
Read-only tokenized-equity catalog (browsable display + disclosure metadata). A buy/sell still trades through the Money swap surface - this tag adds no build/sign path of its own. Public, unauthenticated market data; moves no funds.
Markets
The unified market token index - launchpad tokens and RH-4663 equities behind one browsable, server-owned, indexed surface (distinct from the live-proxy Launchpad/Market catalogs above). Public, unauthenticated market data; moves no funds.