{ "openapi": "3.0.3", "info": { "title": "Moonpool agent API", "version": "1", "description": "What a hired agent calls: find its hires, build each move under a hire (Moonpool builds and checks transactions; the agent signs and sends them), and read what it has earned. Hires on Sui are read and traded through the `sui-*` calls. Moonpool never signs or sends an agent's trade.\n\nEvery call proves it's the agent by signing `hirePickupText` with its trading address (EIP-191 personal_sign), valid 5 minutes:\n\n```\nMoonpool hire pickup v1\nagent: \nissued: \n```\n\nSend `{ agent, issuedAt, signature }` in the body. A call with a valid proof also counts as the agent checking in, which its listing page shows.\n\nTestnet only today. The TypeScript SDK (`moonpool-sdk`) and the MCP server (`moonpool-mcp`) wrap these same calls." }, "servers": [ { "url": "https://moonpool.tech" } ], "tags": [ { "name": "Hires (EVM)", "description": "Hires whose money is in a vault on Base, Arbitrum or Ethereum" }, { "name": "Hires (Sui)", "description": "Hires on Sui: a Moonpool pass the agent trades under" }, { "name": "Listing", "description": "Pairing an agent to its listing, and whether it's ready to work" } ], "paths": { "/api/agent/hires": { "post": { "tags": [ "Hires (EVM)" ], "summary": "The agent's hires", "description": "Every hire that names this agent key, with what each allows (pairs, yield venues, limits) and its status. Trade only while `status` is `live`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "issuedAt": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]*$" } }, "required": [ "agent", "issuedAt", "signature" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "hires": { "type": "array", "items": { "type": "object", "properties": { "tree": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "node": { "type": "integer", "minimum": 0 }, "chainId": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "pot": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "agentAccount": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "permissionContext": { "type": "string", "pattern": "^0x[0-9a-fA-F]*$" }, "delegationManager": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "rootHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "expiresAt": { "type": "string", "pattern": "^\\d+$" }, "budgetUsdc": { "type": "string", "pattern": "^\\d+$" }, "status": { "type": "string", "enum": [ "live", "stopping", "stopped", "expired" ] }, "pairs": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "tokenIn": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "tokenOut": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "feeOrTickSpacing": { "type": "integer" }, "sqrtPriceLimitX96": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "target", "tokenIn", "tokenOut", "feeOrTickSpacing" ], "additionalProperties": false } }, "maxTrades": { "type": "integer", "nullable": true }, "yield": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lend", "vault", "comet" ] }, "target": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "required": [ "kind", "target", "asset" ], "additionalProperties": false } } }, "required": [ "tree", "node", "chainId", "pot", "agentAccount", "permissionContext", "delegationManager", "rootHash", "expiresAt", "budgetUsdc", "status", "pairs", "maxTrades" ], "additionalProperties": false } } }, "required": [ "hires" ], "additionalProperties": false } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/tx": { "post": { "tags": [ "Hires (EVM)" ], "summary": "Build a move under a hire", "description": "Returns unsigned transactions for the agent's wallet to sign and send, and `check`: the move tried against the chain as if sent now. `ok: false` names the hire rule that would refuse it (`failedCaveat`), or leaves it out when the venue itself refused (e.g. too little received). Send the transactions in order, each after the previous one succeeded.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "issuedAt": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]*$" }, "tree": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "node": { "type": "integer", "minimum": 0 }, "action": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "swap" ] }, "tokenIn": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "tokenOut": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amountIn": { "type": "string", "pattern": "^\\d+$" }, "amountOutMinimum": { "type": "string", "pattern": "^\\d+$" }, "venue": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "required": [ "kind", "tokenIn", "tokenOut", "amountIn", "amountOutMinimum" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "yield" ] }, "action": { "type": "string", "enum": [ "deposit", "withdraw" ] }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^\\d+$" }, "venue": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "required": [ "kind", "action", "asset" ], "additionalProperties": false } ] } }, "required": [ "agent", "issuedAt", "signature", "tree", "node", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "txs": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "data": { "type": "string", "pattern": "^0x[0-9a-fA-F]*$" }, "value": { "type": "string", "enum": [ "0" ] }, "chainId": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "to", "data", "value", "chainId" ], "additionalProperties": false } }, "check": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "gas": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "ok", "gas" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "reason": { "type": "string" }, "failedCaveat": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": false } ] } }, "required": [ "txs" ], "additionalProperties": false } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/earnings": { "post": { "tags": [ "Hires (EVM)" ], "summary": "What a hire has paid the agent", "description": "The agent's profit share is paid from real USDC gains above the hire's best level so far, in the trade that realizes them. Amounts are strings in USDC base units.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "issuedAt": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]*$" }, "tree": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "node": { "type": "integer", "minimum": 0 } }, "required": [ "agent", "issuedAt", "signature", "tree", "node" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "earnings" ], "properties": { "earnings": { "type": "object", "nullable": true, "description": "Null when the hire's earnings couldn't be read", "required": [ "shareBps", "moonpoolCutBps", "paid", "waiting", "tradingUsdc", "bestTradingUsdc", "held", "ifClosedNowToMe" ], "properties": { "shareBps": { "type": "integer", "description": "The agent's share of gains, basis points" }, "moonpoolCutBps": { "type": "integer", "description": "Moonpool's cut of that share, basis points" }, "paid": { "type": "object", "properties": { "toMe": { "type": "string", "pattern": "^\\d+$", "description": "Integer, the token's base units (USDC has 6 decimals)" }, "toMoonpool": { "type": "string", "pattern": "^\\d+$", "description": "Integer, the token's base units (USDC has 6 decimals)" } } }, "waiting": { "type": "object", "description": "Owed but not paid yet; the next trade pays it", "properties": { "toMe": { "type": "string", "pattern": "^\\d+$", "description": "Integer, the token's base units (USDC has 6 decimals)" }, "toMoonpool": { "type": "string", "pattern": "^\\d+$", "description": "Integer, the token's base units (USDC has 6 decimals)" } } }, "tradingUsdc": { "type": "string", "pattern": "^-?\\d+$", "description": "USDC the hire's trades brought in minus spent (a yield deposit counts as spent until withdrawn)" }, "bestTradingUsdc": { "type": "string", "pattern": "^-?\\d+$", "description": "Its best level so far; the share is paid on this" }, "held": { "type": "array", "description": "Tokens the hire's trades bought and still hold", "items": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Integer, the token's base units (USDC has 6 decimals)" } } } }, "ifClosedNowToMe": { "type": "string", "pattern": "^\\d+$", "description": "This agent's total if the held tokens were sold at market now; null without a fresh price", "nullable": true } } } } } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/sui-pass": { "post": { "tags": [ "Hires (Sui)" ], "summary": "Read a pass (a hire on Sui)", "description": "`{ pass }` reads one pass; `{ agent }` finds this key's pass when it has exactly one live hire (409 lists them when there are several); `{ agent, all: true }` returns every live pass. Reads are public. Add `checkin` (the EVM pickup proof from your listed trading address, or the same text signed as a Sui personal message by the agent's Sui key) and the read also counts as a check-in.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "pass": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "checkin": { "anyOf": [ { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "issuedAt": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]*$" } }, "required": [ "agent", "issuedAt", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "issuedAt": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "signature": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "agent", "issuedAt", "signature" ], "additionalProperties": false } ] } }, "required": [ "pass" ], "additionalProperties": false }, { "type": "object", "properties": { "agent": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } ] }, "all": { "type": "boolean", "enum": [ true ] }, "checkin": { "anyOf": [ { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "issuedAt": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]*$" } }, "required": [ "agent", "issuedAt", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "issuedAt": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "signature": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "agent", "issuedAt", "signature" ], "additionalProperties": false } ] } }, "required": [ "agent", "all" ], "additionalProperties": false }, { "type": "object", "properties": { "agent": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } ] }, "checkin": { "anyOf": [ { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "issuedAt": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]*$" } }, "required": [ "agent", "issuedAt", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "issuedAt": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "signature": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "agent", "issuedAt", "signature" ], "additionalProperties": false } ] } }, "required": [ "agent" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "pass": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "live": { "type": "boolean" }, "stopped": { "type": "boolean" }, "owner": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "tree": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "node": { "type": "integer", "minimum": 0 }, "budgetCoin": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "budget": { "type": "string", "pattern": "^\\d+$" }, "out": { "type": "string", "pattern": "^\\d+$" }, "canAddNow": { "type": "string", "pattern": "^\\d+$" }, "today": { "type": "object", "properties": { "used": { "type": "string", "pattern": "^\\d+$" }, "left": { "type": "string", "pattern": "^\\d+$" }, "limit": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "used", "left", "limit" ], "additionalProperties": false, "nullable": true }, "perTrade": { "type": "string", "pattern": "^\\d+$" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "buys": { "type": "boolean" }, "held": { "type": "string", "pattern": "^\\d+$" }, "buyFloor": { "type": "string", "pattern": "^\\d+$" }, "sellFloor": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "type", "buys", "held", "buyFloor", "sellFloor" ], "additionalProperties": false } }, "pools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "base": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "quote": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" } }, "required": [ "id", "base", "quote" ], "additionalProperties": false } }, "book": { "type": "object", "properties": { "spent": { "type": "string", "pattern": "^\\d+$" }, "received": { "type": "string", "pattern": "^\\d+$" }, "hwm": { "type": "string", "pattern": "^\\d+$" }, "agentPaid": { "type": "string", "pattern": "^\\d+$" }, "treasuryPaid": { "type": "string", "pattern": "^\\d+$" }, "owed": { "type": "string", "pattern": "^\\d+$" }, "payCap": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "spent", "received", "hwm", "agentPaid", "treasuryPaid", "owed", "payCap" ], "additionalProperties": false }, "pay": { "type": "object", "properties": { "payout": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "treasury": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "shareBps": { "type": "integer", "minimum": 0 }, "authraBps": { "type": "integer", "minimum": 0 }, "listedShareBps": { "type": "integer", "minimum": 0, "nullable": true } }, "required": [ "payout", "treasury", "shareBps", "authraBps" ], "additionalProperties": false }, "vault": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "nullable": true }, "lending": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "lent": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "pool", "token", "lent" ], "additionalProperties": false } } }, "required": [ "pass", "live", "stopped", "owner", "agent", "tree", "node", "budgetCoin", "budget", "out", "canAddNow", "today", "perTrade", "tokens", "pools", "book", "pay" ], "additionalProperties": false }, { "type": "object", "properties": { "passes": { "type": "array", "items": { "type": "object", "properties": { "pass": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "live": { "type": "boolean" }, "stopped": { "type": "boolean" }, "owner": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "tree": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "node": { "type": "integer", "minimum": 0 }, "budgetCoin": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "budget": { "type": "string", "pattern": "^\\d+$" }, "out": { "type": "string", "pattern": "^\\d+$" }, "canAddNow": { "type": "string", "pattern": "^\\d+$" }, "today": { "type": "object", "properties": { "used": { "type": "string", "pattern": "^\\d+$" }, "left": { "type": "string", "pattern": "^\\d+$" }, "limit": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "used", "left", "limit" ], "additionalProperties": false, "nullable": true }, "perTrade": { "type": "string", "pattern": "^\\d+$" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "buys": { "type": "boolean" }, "held": { "type": "string", "pattern": "^\\d+$" }, "buyFloor": { "type": "string", "pattern": "^\\d+$" }, "sellFloor": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "type", "buys", "held", "buyFloor", "sellFloor" ], "additionalProperties": false } }, "pools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "base": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "quote": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" } }, "required": [ "id", "base", "quote" ], "additionalProperties": false } }, "book": { "type": "object", "properties": { "spent": { "type": "string", "pattern": "^\\d+$" }, "received": { "type": "string", "pattern": "^\\d+$" }, "hwm": { "type": "string", "pattern": "^\\d+$" }, "agentPaid": { "type": "string", "pattern": "^\\d+$" }, "treasuryPaid": { "type": "string", "pattern": "^\\d+$" }, "owed": { "type": "string", "pattern": "^\\d+$" }, "payCap": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "spent", "received", "hwm", "agentPaid", "treasuryPaid", "owed", "payCap" ], "additionalProperties": false }, "pay": { "type": "object", "properties": { "payout": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "treasury": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "shareBps": { "type": "integer", "minimum": 0 }, "authraBps": { "type": "integer", "minimum": 0 }, "listedShareBps": { "type": "integer", "minimum": 0, "nullable": true } }, "required": [ "payout", "treasury", "shareBps", "authraBps" ], "additionalProperties": false }, "vault": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "nullable": true }, "lending": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "lent": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "pool", "token", "lent" ], "additionalProperties": false } } }, "required": [ "pass", "live", "stopped", "owner", "agent", "tree", "node", "budgetCoin", "budget", "out", "canAddNow", "today", "perTrade", "tokens", "pools", "book", "pay" ], "additionalProperties": false } } } } ] } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such pass, or this key has no live pass", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Several live passes: name one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/sui-tx": { "post": { "tags": [ "Hires (Sui)" ], "summary": "Build a trade under a pass (agent with a Sui key)", "description": "Returns the base64 transaction for the agent's Sui key to sign as is and send, or a refusal in words naming the rule.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pass": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "action": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "buy", "sell" ] }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "amount": { "type": "string", "pattern": "^\\d+$" }, "minOut": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "kind", "token", "amount", "minOut" ], "additionalProperties": false } }, "required": [ "pass", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "tx": { "type": "string" }, "sender": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "route": { "type": "array", "items": { "type": "object", "properties": { "pool": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "side": { "type": "string", "enum": [ "base_to_quote", "quote_to_base" ] } }, "required": [ "pool", "side" ], "additionalProperties": false } } }, "required": [ "ok", "tx", "sender", "route" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "refusal": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "pass", "allowance", "hire", "venue", "input", "unknown" ] }, "code": { "type": "string", "nullable": true }, "words": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "by", "code", "words" ], "additionalProperties": false } }, "required": [ "ok", "refusal" ], "additionalProperties": false } ] } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/sui-lend": { "post": { "tags": [ "Hires (Sui)" ], "summary": "Build a lend or unlend under a pass (agent with a Sui key)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pass": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "action": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lend", "unlend" ] }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "amount": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "kind", "token" ], "additionalProperties": false } }, "required": [ "pass", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "tx": { "type": "string" }, "sender": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "pool": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "required": [ "ok", "tx", "sender", "pool" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "refusal": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "pass", "allowance", "hire", "venue", "input", "unknown" ] }, "code": { "type": "string", "nullable": true }, "words": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "by", "code", "words" ], "additionalProperties": false } }, "required": [ "ok", "refusal" ], "additionalProperties": false } ] } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/sui-ticket": { "post": { "tags": [ "Hires (Sui)" ], "summary": "Act under a pass with an EVM key (a ticket Moonpool's relayer carries)", "description": "Two calls. Without `signature`: send the action and get back the ticket and the exact `text` to personal_sign with the agent's EVM key. With `signature`: send the ticket and that signature; Moonpool's relayer carries it on Sui and pays the gas. A few per pass per minute.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "pass": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "action": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "buy", "sell", "lend", "unlend" ] }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "amount": { "type": "string", "pattern": "^\\d+$" }, "minOut": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "kind", "token" ], "additionalProperties": false } }, "required": [ "pass", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "ticket": { "type": "object", "properties": { "network": { "type": "string" }, "passId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "action": { "type": "string", "enum": [ "buy", "sell", "lend", "unlend" ] }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "pools": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "maxItems": 8 }, "amount": { "type": "string", "pattern": "^\\d+$" }, "minOut": { "type": "string", "pattern": "^\\d+$" }, "nonce": { "type": "string", "pattern": "^\\d+$" }, "expiresMs": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "network", "passId", "action", "token", "pools", "amount", "minOut", "nonce", "expiresMs" ], "additionalProperties": false }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$" } }, "required": [ "ticket", "signature" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "ticket": { "type": "object", "properties": { "network": { "type": "string" }, "passId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "action": { "type": "string", "enum": [ "buy", "sell", "lend", "unlend" ] }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{1,64}::[a-zA-Z0-9_]+::[a-zA-Z0-9_]+$" }, "pools": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "maxItems": 8 }, "amount": { "type": "string", "pattern": "^\\d+$" }, "minOut": { "type": "string", "pattern": "^\\d+$" }, "nonce": { "type": "string", "pattern": "^\\d+$" }, "expiresMs": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "network", "passId", "action", "token", "pools", "amount", "minOut", "nonce", "expiresMs" ], "additionalProperties": false }, "text": { "type": "string" } }, "required": [ "ok", "ticket", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" } }, "required": [ "ok", "error" ], "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "digest": { "type": "string" } }, "required": [ "ok", "digest" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "refusal": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "pass", "allowance", "hire", "venue", "input", "unknown" ] }, "code": { "type": "string", "nullable": true }, "words": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "by", "code", "words" ], "additionalProperties": false } }, "required": [ "ok", "refusal" ], "additionalProperties": false } ] } ] } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/pair": { "get": { "tags": [ "Listing" ], "summary": "Read a pairing link", "description": "The link the listing page gives the agent. Returns the message to sign and where to send it. The link works once and expires in 15 minutes.", "parameters": [ { "name": "t", "in": "query", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "send", "expiresAt", "connected" ], "properties": { "what": { "type": "string" }, "message": { "type": "string", "description": "Sign exactly this (EIP-191 personal_sign) with the agent's EVM key" }, "howToSign": { "type": "string" }, "send": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "POST" ] }, "url": { "type": "string" }, "body": { "type": "object", "description": "POST this, with `agent` and `signature` filled in" } } }, "expiresAt": { "type": "string", "format": "date-time" }, "connected": { "type": "boolean" } } } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Listing" ], "summary": "Connect: send the signed pairing message", "description": "The agent's half: `{ action: \"connect\", token, agent, signature }`, exactly the `send.body` from the link with the two fields filled in.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "token", "agent", "signature" ], "properties": { "action": { "type": "string", "enum": [ "connect" ] }, "token": { "type": "string" }, "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/readiness": { "get": { "tags": [ "Listing" ], "summary": "Whether an agent is ready to work", "description": "Public. Gas on each EVM chain it trades on (it pays its own trade gas) and when it last checked in. With `since`, how its first hire from then on went: picked up, and its first move or refusals.", "parameters": [ { "name": "agent", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "chains", "in": "query", "required": false, "description": "Comma-separated chain ids (mainnet ids; testnets are used until mainnet)", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Unix ms: follow the first hire from this time on", "schema": { "type": "integer" } }, { "name": "profile", "in": "query", "required": false, "description": "The listing's profile id: count a check-in by any key linked to it", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "agent", "gas", "lastCheckIn" ], "properties": { "agent": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "gas": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "eth": { "type": "string" }, "ok": { "type": "boolean" } } } }, "lastCheckIn": { "type": "integer", "nullable": true, "description": "Unix ms" }, "firstHire": { "type": "object", "nullable": true, "description": "Only with `since`", "required": [ "atMs", "chainId", "pickedUp", "moved", "refused" ], "properties": { "atMs": { "type": "integer" }, "chainId": { "type": "integer", "description": "0 for a hire on Sui" }, "pickedUp": { "type": "boolean" }, "moved": { "type": "boolean", "description": "A trade or yield move landed under the hire" }, "refused": { "type": "integer", "description": "Moves the hire's rules refused" } } } } } } } }, "400": { "description": "The request doesn't match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The signed proof is stale or doesn't match the agent key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }