Skip to main content
The owner retains custody of all funds, collateral movement, and withdrawal rights. The agent may only perform the trading actions defined in its policy. For a conceptual overview see the Delegated Agents.

​
Owner

​
(request: UpsertDelegatedAgentRequest) => Promise<DelegatedAgent>
Create or update the policy for an agent wallet. If an agent with the same agentAddress already exists for this owner, its policy is replaced in full.Parameters:
  • request: UpsertDelegatedAgentRequest
    • agentAddress: string — EVM wallet address of the agent
    • name?: string — human-readable label for the agent
    • allowedActions: DelegatedAgentAction[] — subset of "CREATE_ORDER", "CANCEL_ORDER", "REPLACE_ORDER"
    • allowedTradingPairIds: string[] — trading pair UUIDs the agent may trade
    • allowedMarginAccountIds?: string[] — margin account UUIDs the agent may trade against; omit to allow all
    • allowedOrderTypes?: Array<"LIMIT" | "MARKET"> — omit to allow all
    • allowedTimeInForce?: Array<"GTC" | "IOC" | "FOK"> — omit to allow all
    • maxLeverage?: string — maximum leverage the agent may request, e.g. "10"
    • maxOrderNotional?: string — per-order notional cap in quote asset units, e.g. "100000"
    • maxOpenOrders?: number — cap on the agent’s concurrent open orders
    • expiresAt?: string — ISO 8601 expiry; policy auto-expires at this time
Returns: DelegatedAgent:
  • id: string — UUID, store for revocation
  • ownerUserId: string
  • agentAddress: string
  • name?: string
  • isActive: boolean
  • expiresAt?: string — ISO 8601
  • revokedAt?: string — ISO 8601, set once the agent is revoked
  • allowedActions: string[]
  • allowedTradingPairIds: string[]
  • allowedMarginAccountIds: string[]
  • allowedOrderTypes?: string[]
  • allowedTimeInForce?: string[]
  • maxLeverage?: string
  • maxOrderNotional?: string
  • maxOpenOrders?: number
Example:
​
() => Promise<ListDelegatedAgentsResponse>
Return all delegated agents registered by the authenticated owner.Returns: ListDelegatedAgentsResponse:
  • agents: DelegatedAgent[]
Example:
​
(agentId: string) => Promise<{ status: 'REVOKED' }>
Revoke an agent policy. Orders already submitted are unaffected. Existing delegated auth sessions may still authenticate until their own session expiry, but policy-gated trading fails because Monaco re-checks the active delegation before each create, cancel, replace, or close-position action.Parameters:
  • agentId: string — the id returned by upsertDelegatedAgent
Returns:
  • status: "REVOKED"
Example:

​
Agent

​
() => Promise<ListDelegatedOwnersResponse>
Reverse lookup keyed on the authenticated agent’s own wallet address. Returns the owners that currently have an active delegation to this agent — non-revoked and non-expired only. Use this to discover the ownerUserId to pass into loginAsDelegatedOwner, so the agent does not need the owner’s ID supplied out of band.Returns: ListDelegatedOwnersResponse:
  • owners: DelegatedAgentOwner[]:
    • ownerUserId: string — pass this into loginAsDelegatedOwner
    • delegationId: string — UUID of the delegation record
    • name?: string — the label the owner gave this agent
    • isActive: boolean
    • expiresAt?: string — ISO 8601 expiry of the delegation
Example:
​
(ownerUserId: string) => Promise<AuthState>
Adopt an owner-scoped delegated session and route all subsequent SDK calls through it. This is the method agents should use to act on an owner — it generates a fresh ed25519 session keypair, registers it with createDelegatedSession, and installs the resulting owner-scoped session as the SDK’s active auth state. Every read and trading call after it operates on the owner account, with the agent wallet address preserved as the actor for policy enforcement and audit.The agent must already be authenticated with its own wallet (sdk.login). The owner keeps custody, collateral, positions, PnL, risk, and withdrawal control. The delegated session cannot withdraw, and trading mutations are re-checked against the active policy every time.Parameters:
  • ownerUserId: string — the ownerUserId of the account owner who registered this agent, as returned by listDelegatedOwners
Returns: AuthState — the adopted owner-scoped session:
  • user.id: string — the owner’s user ID (the identity subsequent calls act on)
  • user.address: string — the agent’s wallet address (the preserved actor)
  • expiresAt: number — Unix timestamp (seconds) when the delegated session expires
  • sessionPublicKey / sessionPrivateKey: the freshly generated owner-scoped session keypair
Example:
The strategyKey field causes Monaco to resolve the owner’s parent perps account and target the isolated bucket for the (tradingPair, strategyKey) combination. Omit it to use the owner’s default bucket for the pair. See placeLimitOrder for full order placement options.
​
(request: CreateDelegatedSessionRequest) => Promise<CreateDelegatedSessionResponse>
Low-level primitive that exchanges the agent’s own authenticated session for an owner-scoped delegated session record. Prefer loginAsDelegatedOwner (above), which calls this and then installs the resulting keypair as the SDK’s active session. Calling createDelegatedSession on its own registers a session but does not switch the SDK to it, so subsequent calls keep signing with the agent’s own session and act on the agent account, not the owner.The agent must first authenticate with its own wallet via the standard session-key login. A delegated session acts against the owner account while preserving the agent wallet address as the actor. The owner keeps custody, collateral, positions, PnL, risk, and withdrawal control. The delegated session cannot withdraw, and trading mutations are checked against the active policy every time they are submitted.Parameters:
  • request: CreateDelegatedSessionRequest
    • ownerUserId: string — the ownerUserId of the account owner who registered this agent, as returned by listDelegatedOwners
    • sessionPublicKey: string — the lowercase-hex (64-char) ed25519 session public key the agent generates for this delegated session; subsequent requests acting on the owner’s behalf are signed with the matching private key
Returns: CreateDelegatedSessionResponse:
  • expiresAt: number — Unix timestamp when the delegated session expires
  • delegationId: string — UUID of the active delegation record
  • ownerUserId: string — the owner’s user ID
  • agentAddress: string — the agent’s wallet address

​
Policy Enforcement

Delegated sessions are not a one-time permission check. Monaco reloads the active delegation before create, cancel, replace, and close-position actions. The request fails if the policy is revoked, expired, inactive, missing, or narrower than the requested action. Close-position calls are checked like order creation because they submit a close or reduce order. For delegated batch close-all flows, scope the request to an explicit trading pair so the policy check cannot accidentally cover every open market.

​
Errors

  • 403 — agent wallet is not registered to the given owner, the policy is expired, or the requested action is outside the agent’s allowedActions
  • 403 — createDelegatedSession called from a non-agent wallet (the agent must authenticate with its own address first)
  • 409 — createDelegatedSession called with a sessionPublicKey that is already registered (for example, reused from a prior session). Generate a fresh ed25519 session keypair per session
  • 404 — revokeDelegatedAgent called with an agentId that does not belong to the authenticated owner