---
title: "Set the org default payout wallet for tenant priced routes"
method: PATCH
path: "/orgs/v1/{org_id}/payout-wallet"
tags: ["Org"]
---

# Set the org default payout wallet for tenant priced routes

`PATCH /orgs/v1/{org_id}/payout-wallet`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/orgs/v1/{org_id}/payout-wallet`
- Auth: one of:
  - HTTP bearer
  - API key in header `SIGN-IN-WITH-X`
  - API key in header `x-admin-key`

Admin/owner-only, with step-up or fresh SIWX. The wallet must already be active and linked to this organization. Use null to clear the explicit default; a single active org wallet may still resolve as the payout wallet. A changed destination first establishes a payment-generation drain. While a prior-generation settlement or delivery lease remains non-terminal, this route returns 409 PAYMENT_DESTINATION_DRAINING with Retry-After and an identical-request retry action; the payout epoch advances only with the final atomic wallet change.

## Path parameters

- `org_id` string, uuid, required

## Request body

- PayoutWalletSetRequest: Exactly one of wallet_address (an active wallet linked to this organization, or null to clear) or signer_id (a signer owned by one of this organization's projects; its address becomes the payout address, so receipts from priced routes land where payouts leave from).
  - `wallet_address` string, nullable: Active wallet linked to this organization, or null to clear the explicit default.
  - `signer_id` string: An active signer owned by a project of this organization.

## Response `200`

Default payout wallet set or cleared.

- PayoutWalletSetResponse
  - `status` 'set' | 'cleared', required
  - `org_id` string, uuid, required
  - `default_payout_wallet` string, nullable, required
  - `previous_default_payout_wallet` string, nullable, required
  - `recovery` PayoutWalletRecovery, required
    - `status` 'ready' | 'required' | 'ambiguous', required
    - `active_wallet_count` integer, required
    - `next_actions` PayoutWalletNextAction[], required
      - `type` 'edit_request' | 'resume_deploy', required
      - `method` 'POST' | 'PATCH', required
      - `path` string, required
      - `auth` string, required
      - `why` string, required
    - `mode` 'default' | 'single_active_wallet', nullable: Present when status is ready.
    - `wallet_address` string, nullable: Resolved payout wallet when status is ready.
    - `code` 'PAYOUT_WALLET_REQUIRED' | 'PAYOUT_WALLET_AMBIGUOUS' | 'null', nullable: Present when payout setup needs recovery.

## Other responses

- `400`: Invalid wallet or wallet is not actively linked to this org.
- `403`: Caller is not an org admin/owner or lacks fresh auth.
- `409`: PAYMENT_DESTINATION_DRAINING — retry the identical payout-wallet mutation after Retry-After. The body exposes the owned mutation id, cutoff epoch, blocker/lease counts, expected resolution time, funds_moved:false, and canonical next_actions[].

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)