> ## Documentation Index > Fetch the complete documentation index at: https://docs.hifi.com/llms.txt > Use this file to discover all available pages before exploring further. # Deactivate an orchestration address > Soft-delete the address: sets `status=DEACTIVATED` and `deactivatedAt=now()`. Requires a `walletAddress` in the body — any deposits still `PENDING` (not yet rolled into a batch) are refunded in-kind to it. The claim and refund run atomically under the address row lock, so a deposit can never be both offramped and refunded. Idempotent — calling on an already-deactivated address returns 200 with the current record and issues no second refund. **After deactivation:** * The on-chain wallet still exists and can receive funds (we can't take it offline). * Incoming deposits are recorded with `status=IGNORED` and `ignoredReason=ADDRESS_DEACTIVATED`. A Slack alert fires for manual ops follow-up. These are NOT auto-refunded — only the deposits that were `PENDING` at deactivation are. * The escrow wallet stays locked to this address (it's never returned to the general allocation pool). * Batches already in `PROCESSING` continue to completion; batches still `PENDING` will be marked `FAILED` with `failureReason=ADDRESS_NOT_ACTIVE` on the next worker tick. ## OpenAPI ````yaml https://production.hifi.com/api/v2/openapi.json post /v2/users/{userId}/orchestration-addresses/{orchestrationAddressId}/deactivate openapi: 3.0.0 info: title: Hifi API version: 2.0.0 description: API documentation for Hifi servers: - url: https://production.hifibridge.com description: Production server - url: https://sandbox.hifibridge.com description: Sandbox server security: - bearerAuth: [] tags: - name: Common description: Common endpoints - name: User description: User endpoints - name: Kyc description: Kyc endpoints - name: Wallet description: Wallet endpoints - name: Account description: Account endpoints - name: External Account description: External Account endpoints for managing beneficiary bank accounts - name: Fiat Account description: Fiat Account endpoints - name: Virtual Account description: Virtual Account endpoints - name: Onramp description: Onramp endpoints - name: Offramp description: Offramp endpoints - name: Orchestration Address description: >- Orchestration Address endpoints — persistent on-chain wallets that automatically off-ramp incoming stablecoin deposits to a USD bank account - name: Crypto Transfer description: Crypto Transfer endpoints - name: Cross-Chain Bridge description: Cross-Chain Bridge endpoints - name: Token Swap description: Token Swap endpoints - name: Canton Offers description: Canton Offers endpoints - name: Transfer Rules description: Transfer approval rules and configuration - name: Transfer Approvals description: Transfer approval workflow and admin actions - name: File description: File endpoints - name: Reporting description: Reporting and metrics endpoints paths: /v2/users/{userId}/orchestration-addresses/{orchestrationAddressId}/deactivate: post: tags: - Orchestration Address summary: Deactivate an orchestration address description: > Soft-delete the address: sets `status=DEACTIVATED` and `deactivatedAt=now()`. Requires a `walletAddress` in the body — any deposits still `PENDING` (not yet rolled into a batch) are refunded in-kind to it. The claim and refund run atomically under the address row lock, so a deposit can never be both offramped and refunded. Idempotent — calling on an already-deactivated address returns 200 with the current record and issues no second refund. **After deactivation:** * The on-chain wallet still exists and can receive funds (we can't take it offline). * Incoming deposits are recorded with `status=IGNORED` and `ignoredReason=ADDRESS_DEACTIVATED`. A Slack alert fires for manual ops follow-up. These are NOT auto-refunded — only the deposits that were `PENDING` at deactivation are. * The escrow wallet stays locked to this address (it's never returned to the general allocation pool). * Batches already in `PROCESSING` continue to completion; batches still `PENDING` will be marked `FAILED` with `failureReason=ADDRESS_NOT_ACTIVE` on the next worker tick. parameters: - $ref: '#/components/parameters/UserIdPathParameter' - $ref: '#/components/parameters/OrchestrationAddressIdPathParameter' requestBody: $ref: '#/components/requestBodies/DeactivateOrchestrationAddressBody' responses: '200': $ref: '#/components/responses/OrchestrationAddressResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '404': $ref: '#/components/responses/NotFoundResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: parameters: UserIdPathParameter: name: userId in: path schema: type: string description: ID of the user required: true OrchestrationAddressIdPathParameter: name: orchestrationAddressId in: path schema: type: string format: uuid required: true description: ID of the orchestration address. requestBodies: DeactivateOrchestrationAddressBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeactivateOrchestrationAddress' responses: OrchestrationAddressResponse: description: A single orchestration address record. content: application/json: schema: $ref: '#/components/schemas/OrchestrationAddressObject' BadRequestResponse: description: Bad request - validation error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object description: Field-specific validation errors UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' NotFoundResponse: description: Resource not found content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string InternalServerErrorResponse: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' schemas: DeactivateOrchestrationAddress: type: object title: Deactivate Orchestration Address description: > Body for deactivating an orchestration address. Any deposits still `PENDING` (not yet rolled into a batch) are refunded in-kind to `walletAddress`. required: - walletAddress properties: walletAddress: type: string description: > Destination address for the in-kind refund of the address's `PENDING` deposits. Must be a valid address for the orchestration address's `chain` (else `400 FIELD_VALIDATION_ERROR`). Required even when there are no pending deposits to refund. OrchestrationAddressObject: type: object description: An orchestration address record. properties: id: type: string format: uuid description: Unique orchestration address ID. userId: type: string format: uuid description: ID of the user that owns this orchestration address. address: type: string nullable: true description: | The on-chain wallet address that accepts deposits. `null` while `status=PENDING_WALLET` (provisioning in flight); populated once the wallet exists. example: '0xAbC0123456789AbCdEf0123456789AbCdEf01234' source: type: object description: Source token + chain the address accepts. properties: currency: type: string enum: - usdc - usdt chain: type: string description: > Abbreviated chain name (e.g. `BASE`, `ETHEREUM`, `SOLANA`) — the same form accepted on create and used across the v2 API. example: BASE destination: type: object description: Destination payout configuration. properties: currency: type: string enum: - usd accountId: type: string format: uuid mode: $ref: '#/components/schemas/OrchestrationAddressModeEnum' schedule: description: | Populated only when `mode=SCHEDULED`; `null` otherwise. nullable: true type: object properties: interval: $ref: '#/components/schemas/OrchestrationScheduleIntervalEnum' nextRunAt: type: string format: date-time description: ISO 8601 timestamp of the next scheduled batch. thresholdAmount: type: string nullable: true description: > Populated only when `mode=THRESHOLD`; `null` otherwise. Decimal amount in the source `currency`. example: '100.00' status: $ref: '#/components/schemas/OrchestrationAddressStatusEnum' createdAt: type: string format: date-time updatedAt: type: string format: date-time deactivatedAt: type: string format: date-time nullable: true description: >- ISO 8601 timestamp when the address was deactivated. `null` if still active. balance: type: object nullable: true description: > The escrow wallet's live on-chain balance of the source token. Present ONLY on the single-address GET (`GET /orchestration-addresses/{id}`); the list endpoint omits it to avoid a provider call per row. `null` if the wallet isn't provisioned yet or the balance lookup failed — the GET still returns `200`. properties: currency: type: string enum: - usdc - usdt amount: type: string description: Decimal balance in the source `currency` (e.g. `"100.500000"`). example: currency: usdc amount: '100.500000' Unauthorized: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed error message InternalServerError: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed error message OrchestrationAddressModeEnum: type: string enum: - PER_DEPOSIT - SCHEDULED - THRESHOLD description: | Determines when deposits are converted into an offramp. * `PER_DEPOSIT` — each deposit is batched into its own offramp immediately, UNLESS the cumulative `PENDING` amount is below the destination rail's offramp minimum, in which case the deposit is held `PENDING` and all pending deposits are batched together once their cumulative amount reaches the minimum. * `SCHEDULED` — deposits accumulate until the next schedule boundary (`HOURLY`/`DAILY`/`WEEKLY`), then the entire pending pool is batched together (only if it meets the offramp minimum; otherwise it rolls into the next tick). * `THRESHOLD` — deposits accumulate until their summed amount reaches `thresholdAmount`, then the entire pending pool is batched. OrchestrationScheduleIntervalEnum: type: string enum: - HOURLY - DAILY - WEEKLY description: >- How often a `SCHEDULED` orchestration address rolls up pending deposits into a batch. OrchestrationAddressStatusEnum: type: string enum: - PENDING_WALLET - ACTIVE - DEACTIVATED description: | Lifecycle status of the orchestration address. * `PENDING_WALLET` — created but the escrow wallet is still being provisioned. The on-chain `address` is null. Typically transient (a few seconds). * `ACTIVE` — wallet provisioned, ready to receive deposits. * `DEACTIVATED` — soft-deleted. The on-chain wallet still exists and can receive funds, but incoming deposits are recorded with `status=IGNORED` and never offramped. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````