> ## Documentation Index > Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsert delegated agent > Register or update a delegated agent. Master accounts only. Creates (or updates, keyed on `agent_address`) a delegation linking the calling owner to an agent wallet, together with the policy that constrains what the agent may do on the owner's behalf. An owner holds at most 10 active, unexpired agents; a new one past that is rejected until one is revoked or expires. Binding an agent to one margin account (`allowed_margin_account_ids`) makes it that sub-account's key. ## OpenAPI ````yaml /proto-openapi/api/openapi.yaml post /api/v1/delegated-agents openapi: 3.0.3 info: title: Monaco Protocol API description: REST API for the Monaco Protocol hybrid CLOB exchange. version: 1.0.0 servers: - url: https://staging.apimonaco.xyz description: Staging server (Testnet) security: [] tags: - name: AccountsService - name: ApplicationsService - name: AuthService - name: BuildercodeRewardsService - name: CopyTradingService - name: DelegatedAgentsService - name: FaucetService - name: FeesService - name: HealthService - name: ManagedMarketsService description: |- Wallet-authenticated maker assignments. The signed session must match both configured maker user and application. Owner IDs are process fences, never auth. Only wallet sessions are supported; delegated-agent sessions receive 403. - name: MarginAccountsService description: |- Current public isolated-margin semantics: - a user has one parent margin account per application scope - opening orders create or reuse isolated position buckets under that parent - parent account creation is handled internally by margin workflows - name: MarketService - name: OrderbookService - name: OrdersService - name: PositionsService description: |- Current public isolated-margin semantics: - positions link to a parent margin account and, when applicable, a bucket id - opening orders create or reuse isolated position buckets under the parent - users can open another isolated position by reusing the parent account with a different market bucket - name: PulseService - name: SweeperService - name: TraderCodeService - name: TradesService - name: WhitelistService - name: WithdrawalsService paths: /api/v1/delegated-agents: post: tags: - DelegatedAgentsService - DelegatedAgents summary: Upsert delegated agent description: |- Register or update a delegated agent. Master accounts only. Creates (or updates, keyed on `agent_address`) a delegation linking the calling owner to an agent wallet, together with the policy that constrains what the agent may do on the owner's behalf. An owner holds at most 10 active, unexpired agents; a new one past that is rejected until one is revoked or expires. Binding an agent to one margin account (`allowed_margin_account_ids`) makes it that sub-account's key. operationId: upsert_delegated_agent requestBody: content: application/json: schema: $ref: '#/components/schemas/UpsertDelegatedAgentRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DelegatedAgent' '400': description: Invalid request '401': description: Authentication required '403': description: Only master accounts can manage delegated agents '500': description: Internal server error security: - monacoSignature: [] - monacoHttpSignature: [] components: schemas: UpsertDelegatedAgentRequest: required: - agentAddress - allowedActions - allowedTradingPairIds type: object properties: agentAddress: example: '0x742d35cc6634c0532925a3b8d4060f31e2c3d8b5' type: string description: Agent wallet address (EVM, 42 chars including 0x) name: example: market-maker-bot type: string description: Optional human-friendly label for the agent nullable: true expiresAt: example: '2026-12-31T23:59:59Z' type: string description: >- Delegation expiry timestamp (ISO 8601). Ends delegated reads, trading, and session refresh. Omit for the default of 14 days from now; at most 180 days ahead. nullable: true allowedActions: example: - CREATE_ORDER - CANCEL_ORDER type: array items: type: string minLength: 1 description: >- Required JSON array of actions the agent may perform: CREATE_ORDER, CANCEL_ORDER, REPLACE_ORDER, READ, MANAGE_RISK_BUCKETS. Every delegated session may read the owner's data; a policy listing only READ, or no action, is a read-only key. MANAGE_RISK_BUCKETS lets the agent move a margin account's free collateral into that account's own risk buckets (POST /api/v1/margin/risk-buckets/collateral/transfer-in), only for an account listed in allowedMarginAccountIds and, if the policy lists markets, only into an isolated risk bucket on a listed market. No action lets an agent move collateral any other way. Any other value is rejected. allowedTradingPairIds: type: array items: type: string minLength: 1 format: uuid description: >- Required JSON array of trading pair UUIDs. Each listed scope must match: with markets and margin accounts both listed, an order needs a listed market AND a listed account. Send [] for account-only scope; both scopes empty permit no orders. allowedMarginAccountIds: type: array items: type: string minLength: 1 format: uuid description: >- Optional JSON array of margin account UUIDs the agent is bound to. When listed, an order must be on one of these accounts (and on a listed market, if any are listed). Omitted, null, or [] leaves the account unrestricted; both scopes empty permit no orders. nullable: true allowedOrderTypes: example: - LIMIT type: array items: type: string minLength: 1 description: >- Optional JSON array of permitted order types (LIMIT, MARKET). Omitted, null, or [] means unrestricted order types. nullable: true allowedTimeInForce: example: - GTC type: array items: type: string minLength: 1 description: >- Optional JSON array of permitted time-in-force values (GTC, IOC, FOK). Omitted, null, or [] means unrestricted time in force. nullable: true maxLeverage: example: '10' type: string description: >- Maximum leverage the agent may use (decimal string). Omit for no limit. nullable: true maxOrderNotional: example: '50000' type: string description: >- Maximum order notional (price * quantity, decimal string). Omit for no limit. nullable: true maxOpenOrders: type: integer description: >- Unsupported legacy field. Requests that set maxOpenOrders are rejected; no concurrent open-order cap is enforced. Omit this field. format: int32 nullable: true ipAllowlist: example: - 203.0.113.0/24 type: array items: type: string minLength: 1 description: >- Optional JSON array of up to 20 IP addresses or CIDR ranges the agent may create its delegated session from. Omitted, null, or [] allows any address. nullable: true DelegatedAgent: type: object properties: id: example: 123e4567-e89b-12d3-a456-426614174000 type: string description: Delegation UUID format: uuid nullable: true ownerUserId: type: string description: Owner account UUID the agent acts on behalf of format: uuid nullable: true agentAddress: example: '0x742d35cc6634c0532925a3b8d4060f31e2c3d8b5' type: string description: Agent wallet address (EVM) nullable: true name: type: string description: Human-friendly label for the agent nullable: true isActive: type: boolean description: Whether the delegation is active nullable: true expiresAt: type: string description: Delegation expiry timestamp (ISO 8601), if set nullable: true revokedAt: type: string description: Revocation timestamp (ISO 8601), if revoked nullable: true allowedActions: type: array items: type: string minLength: 1 description: Actions the agent may perform nullable: true allowedTradingPairIds: type: array items: type: string minLength: 1 format: uuid description: Trading pair UUIDs the agent may trade nullable: true allowedMarginAccountIds: type: array items: type: string minLength: 1 format: uuid description: Margin account UUIDs the agent may trade against nullable: true allowedOrderTypes: type: array items: type: string minLength: 1 description: Permitted order types. Empty means unrestricted. nullable: true allowedTimeInForce: type: array items: type: string minLength: 1 description: Permitted time-in-force values. Empty means unrestricted. nullable: true maxLeverage: type: string description: Maximum leverage (decimal string), if set nullable: true maxOrderNotional: type: string description: Maximum order notional (decimal string), if set nullable: true maxOpenOrders: type: integer description: >- Legacy field; no concurrent open-order cap is enforced. New or updated policies leave it unset. format: int32 nullable: true ipAllowlist: type: array items: type: string minLength: 1 description: >- IP addresses and CIDR ranges the agent may create its delegated session from, normalized. Empty allows any address. nullable: true securitySchemes: monacoSignature: type: apiKey description: >- Ed25519 session-key request signing. Every authenticated request carries three headers: `X-Monaco-PublicKey` (64-char lowercase-hex session public key), `X-Monaco-Timestamp` (Unix milliseconds, within 30s of server time), and `X-Monaco-Signature` (hex ed25519 signature). The signature is over `METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)`, where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from `POST /api/v1/auth/challenge` followed by `POST /api/v1/auth/verify`. name: X-Monaco-Signature in: header monacoHttpSignature: type: apiKey description: >- RFC 9421 Ed25519 session-key request signatures. Send Signature-Input, Signature, and Content-Digest together; never combine them with X-Monaco-* credentials. The monaco signature covers @method, @path, @query, and content-digest in that order, with created (Unix seconds within 30s of server time), keyid (registered lowercase-hex session public key), and alg=ed25519 parameters. Content-Digest uses RFC 9530 sha-256 over the exact body bytes, including the empty body. Query coverage retains ordering and percent encoding. Timestamp freshness does not reject repeated identical requests; use endpoint idempotency where supported. Existing legacy signing remains supported during server-first migration; SDK RFC 9421 signing is opt-in. See https://docs.0xmonaco.com/reference/http-message-signatures for the complete profile and trust model. name: Signature in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.