wallet:sweep

wallet family

Settle an agent's balance above its float to its claimed owner on the owner's signed order — is a sweep due, verify the order, or settle it. Never signs; the destination is never a request field

Effect: ask; Awaits an outcome — the call returns the response below.
Caller: owner; The class of authority the caller must already hold, decided from the attested context with no round trip.
Cost: variable; What one call costs, so you can budget before acting.
Reversible: no; This cannot be undone. Dry-run it first where the contract allows.
Settles: onchain; Moves real, permanent value on chain.
Idempotent: no; Not safe to blind-retry — dedupe on the envelope idempotencyKey.

Send it with your agent

One click hands your coding agent a prompt that registers the substrate, reads this contract, and makes the call. Launch opens the app; the others copy the prompt.

Claude Code

Codex

Cursor

Gemini CLI

Claude Desktop

ChatGPT

curl -X POST https://one.ie/api/ask/wallet:sweep \
  -H "Authorization: Bearer $ONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": { "actor": "scout", "chain": "sui", "balance": "7250000000" }}'

The key is never in a link. npx -y @oneie/cli login writes it to ~/.config/oneie/key on your machine.

Request

Validated before dispatch — an invalid payload is refused with the fix, never half-applied.

actor string optional The agent whose wallet is swept; defaults to `workspace` (an agent workspace)
workspace string optional The workspace that holds the agent's wallets row; defaults to the attested caller
chain sui | evm | solana | btc optional Wallet chain family; default sui
balance any optional Due / verify modes: the agent's balance on `chain` in INTEGER BASE UNITS (mist, wei, lamports, sats) as a digit string. Anything else is refused — never read as 0
order any optional Verify mode: { destination, amount (base-unit digit string), nonce (16–128 of [A-Za-z0-9_-]), expiresAt (unix ms) } as the owner signed it
signature any optional Verify mode: { publicKey, signature } (hex) by the owner's proven address over the 'ONE sweep order' statement
nonce any optional Settle mode: the nonce of an order this door already verified
pending boolean optional Pending mode (the agent runtime's read): the owner's proven address, the agent's address and every unsettled, unexpired order with its owner signature
paymentTx any optional Settle mode: the tx hash of the transfer the agent's runtime signed for exactly the verified order
to any optional REFUSED — the destination is the owner's proven address, never a request field
destination any optional REFUSED — see `to` (the order's own destination lives inside `order`)
address any optional REFUSED — see `to`
treasury any optional REFUSED — see `to`
treasuries any optional REFUSED — see `to`
userAddress any optional REFUSED — the sender is the agent's own wallets row

Response

What comes back from the call.

ok boolean
due boolean Due mode: the balance is above the threshold; ask the owner for an order up to maxUnits
verified boolean Verify mode: the owner's order is valid and recorded — perform the transfer it names
settled boolean Settle mode: pay.one.ie claimed the transfer at the owner's address
reason string
workspace string
actor string
chain string
owner string The claimed owner (actor_owners)
to string The owner's proven address — resolved server-side, never supplied
nonce string
amountUnits string
amount string amountUnits as an exact token decimal
maxUnits string Due mode: balance − float, the most an order may move
pending boolean
agentAddress string Pending mode: the agent's own address on `chain` — the runner checks its key derives it
floatUnits string
orders object[] Pending mode: unsettled, unexpired orders the current owner signed to its current proven address
keepUnits string
freeUnits string
thresholdUnits string
expiresAt number
stage string Settle mode failure: which pay.one.ie stage refused
paymentTx string
receipt object
closed mark | warn | dissolve How this signal closed its loop
error string destination_not_accepted | unsupported_chain | no_wallet | not_an_agent_wallet | no_agent_address | unclaimed | agent_owns_itself | forbidden | owner_address_unproven | destination_is_agent | no_sweep_rule | rule_owner_changed | owner_address_changed | bad_rule | unreadable_balance | order_invalid | order_destination_mismatch | order_expired | order_expiry_too_far | order_amount_exceeds_free_balance | amount_not_representable | order_signature_invalid | order_replayed | order_required | order_already_settled | paymentTx_invalid | treasury_mismatch | not_claimed | a pay.one.ie error

Traffic

Every call to wallet:sweep, counted where it is dispatched — over HTTP or in-process alike. Aggregate only — no actor, no payload, no workspace.

Counting…

Wiring

Every place in the open source that names wallet:sweep, and the file that answers it. Read from the tree at build time — a receiver is reached by NAME through one door, so there is no import edge to follow and a grep is the honest shape of the question. Structure, not volume — the count is in Traffic above.

Called from

API route 2

one.ie/web/src/lib/receiver-index.generated.ts:401
one.ie/web/src/lib/wallet-sweep.ts:9

CLI 1

packages/cli/src/key-sweep.ts:129

SDK 1

packages/sdk/src/sweep-runner.ts:101

→

Answered by

wallet:sweep one.ie/web/src/lib/resolvers/wallet.ts:1281 Dispatched through POST /api/ask/wallet:sweep, after the envelope validates the payload.

wallet family · 10 more

wallet:challenge wallet:create wallet:get wallet:invoice wallet:portfolio wallet:rehearse wallet:send wallet:sweep-set wallet:transactions wallet:transfer

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "actor": {
      "description": "The agent whose wallet is swept; defaults to `workspace` (an agent workspace)",
      "type": "string"
    },
    "workspace": {
      "description": "The workspace that holds the agent's wallets row; defaults to the attested caller",
      "type": "string"
    },
    "chain": {
      "description": "Wallet chain family; default sui",
      "type": "string",
      "enum": [
        "sui",
        "evm",
        "solana",
        "btc"
      ]
    },
    "balance": {
      "description": "Due / verify modes: the agent's balance on `chain` in INTEGER BASE UNITS (mist, wei, lamports, sats) as a digit string. Anything else is refused — never read as 0"
    },
    "order": {
      "description": "Verify mode: { destination, amount (base-unit digit string), nonce (16–128 of [A-Za-z0-9_-]), expiresAt (unix ms) } as the owner signed it"
    },
    "signature": {
      "description": "Verify mode: { publicKey, signature } (hex) by the owner's proven address over the 'ONE sweep order' statement"
    },
    "nonce": {
      "description": "Settle mode: the nonce of an order this door already verified"
    },
    "pending": {
      "description": "Pending mode (the agent runtime's read): the owner's proven address, the agent's address and every unsettled, unexpired order with its owner signature",
      "type": "boolean"
    },
    "paymentTx": {
      "description": "Settle mode: the tx hash of the transfer the agent's runtime signed for exactly the verified order"
    },
    "to": {
      "description": "REFUSED — the destination is the owner's proven address, never a request field"
    },
    "destination": {
      "description": "REFUSED — see `to` (the order's own destination lives inside `order`)"
    },
    "address": {
      "description": "REFUSED — see `to`"
    },
    "treasury": {
      "description": "REFUSED — see `to`"
    },
    "treasuries": {
      "description": "REFUSED — see `to`"
    },
    "userAddress": {
      "description": "REFUSED — the sender is the agent's own wallets row"
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "due": {
      "description": "Due mode: the balance is above the threshold; ask the owner for an order up to maxUnits",
      "type": "boolean"
    },
    "verified": {
      "description": "Verify mode: the owner's order is valid and recorded — perform the transfer it names",
      "type": "boolean"
    },
    "settled": {
      "description": "Settle mode: pay.one.ie claimed the transfer at the owner's address",
      "type": "boolean"
    },
    "reason": {
      "type": "string"
    },
    "workspace": {
      "type": "string"
    },
    "actor": {
      "type": "string"
    },
    "chain": {
      "type": "string"
    },
    "owner": {
      "description": "The claimed owner (actor_owners)",
      "type": "string"
    },
    "to": {
      "description": "The owner's proven address — resolved server-side, never supplied",
      "type": "string"
    },
    "nonce": {
      "type": "string"
    },
    "amountUnits": {
      "type": "string"
    },
    "amount": {
      "description": "amountUnits as an exact token decimal",
      "type": "string"
    },
    "maxUnits": {
      "description": "Due mode: balance − float, the most an order may move",
      "type": "string"
    },
    "pending": {
      "type": "boolean"
    },
    "agentAddress": {
      "description": "Pending mode: the agent's own address on `chain` — the runner checks its key derives it",
      "type": "string"
    },
    "floatUnits": {
      "type": "string"
    },
    "orders": {
      "description": "Pending mode: unsettled, unexpired orders the current owner signed to its current proven address",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nonce": {},
          "destination": {},
          "amountUnits": {
            "type": "string"
          },
          "expiresAt": {
            "type": "number"
          },
          "signature": {}
        },
        "required": [
          "nonce",
          "destination",
          "amountUnits",
          "expiresAt",
          "signature"
        ]
      }
    },
    "keepUnits": {
      "type": "string"
    },
    "freeUnits": {
      "type": "string"
    },
    "thresholdUnits": {
      "type": "string"
    },
    "expiresAt": {
      "type": "number"
    },
    "stage": {
      "description": "Settle mode failure: which pay.one.ie stage refused",
      "type": "string"
    },
    "paymentTx": {
      "type": "string"
    },
    "receipt": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "url": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "url"
      ]
    },
    "closed": {
      "description": "How this signal closed its loop",
      "type": "string",
      "enum": [
        "mark",
        "warn",
        "dissolve"
      ]
    },
    "error": {
      "description": "destination_not_accepted | unsupported_chain | no_wallet | not_an_agent_wallet | no_agent_address | unclaimed | agent_owns_itself | forbidden | owner_address_unproven | destination_is_agent | no_sweep_rule | rule_owner_changed | owner_address_changed | bad_rule | unreadable_balance | order_invalid | order_destination_mismatch | order_expired | order_expiry_too_far | order_amount_exceeds_free_balance | amount_not_representable | order_signature_invalid | order_replayed | order_required | order_already_settled | paymentTx_invalid | treasury_mismatch | not_claimed | a pay.one.ie error",
      "type": "string"
    }
  },
  "required": [
    "ok"
  ]
}