agent.drain
drain(agentId, maxAmount?) → DrainResultTransfer OKRW from the agent's AA wallet back to the owner's primary wallet. An amount above the agent's spendingLimit is sent in several transfers, each no larger than the limit. The owner address is always allowed, regardless of allowedTargets.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
agentId | string | ✓ | The UUID of the agent to drain. |
maxAmount | string | - | Optional cap on the total amount to return, as a decimal OKRW string. Omit it to drain the whole balance. |
Returns
Type:
object { agent, totalDrained, unit, txHashes, chunkCount, remainingBalance } once every transfer has confirmed on-chain. totalDrained and remainingBalance are decimal OKRW strings.
Errors
| Code | Name | Description |
|---|---|---|
AGENT_NOT_ACTIVE | AgentNotActive | Agent is PENDING, FROZEN, or REVOKED. |
INSUFFICIENT_BALANCE | InsufficientBalance | The agent's balance is 0, so there is nothing to drain. |
TX_FAILED | TxFailed | A transfer failed partway through; earlier transfers may have completed, and detail reports drainedSoFar and remainingBalance. Retryable: call agent.drain again to continue. |
Examples
Drain up to 500 OKRW
{
"agentId": "123e4567-e89b-12d3-a456-426614174000",
"maxAmount": "500"
}