HIhifi
Orchestration Address

Update an orchestration address

Changed on

Partial update of an existing orchestration address. Any combination of mode, schedule, thresholdAmount, offrampMessage, and destination.accountId may be passed.

Behavior notes:

  • Switching mode wipes the irrelevant config columns.
  • Changing schedule.interval without an explicit nextRunAt resets the next tick to now + newInterval.
  • Changing destination.accountId re-validates the new account.
  • Queued batches use the current settings when the worker reads the OA to begin creating their offramp. Later edits do not change that attempt or the saved message of an initialized offramp, including on retry.

Cannot update a DEACTIVATED address — returns 400 RESOURCE_CONFLICT. If the destination, message, mode, or status changes after validation but before the update is saved, returns 409 RESOURCE_CONFLICT; reload the settings and retry.

post/v2/users/{userId}/orchestration-addresses/{orchestrationAddressId}/update

Request

  • Base URL
    https://production.hifibridge.com
  • URL
    https://production.hifibridge.com/v2/users/{userId}/orchestration-addresses/{orchestrationAddressId}/update
  • Auth
    HTTP bearer

Path parameters

userIdstring required

ID of the user

orchestrationAddressIdstring uuid required

ID of the orchestration address.

Request body

offrampMessagestring nullable

Optional payment message, preserved exactly. Wire allows at most four lines of 35 characters; ACH allows 10 characters; SWIFT allows 12. Only printable ASCII and newlines are accepted; backslashes and other control characters are rejected. Nonempty messages are unsupported for RTP and other rails. Missing, null, or empty means no message on create; on update omission preserves the setting and null or empty clears it. A destination change revalidates the saved or supplied message. Returns null when unset. Queued batches read current settings when initializing an offramp; initialized offramps retain their saved message on retry.

mode'PER_DEPOSIT' | 'SCHEDULED' | 'THRESHOLD'

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.
thresholdAmountstring nullable

New aggregate threshold. Required if the resulting mode is THRESHOLD, and must be at least the destination rail's offramp minimum (else 400).

Example request

{
  "offrampMessage": "Invoice 42"
}

Response

A single orchestration address record.

idstring uuid

Unique orchestration address ID.

userIdstring uuid

ID of the user that owns this orchestration address.

addressstring nullable

The on-chain wallet address that accepts deposits. null while status=PENDING_WALLET (provisioning in flight); populated once the wallet exists.

offrampMessagestring nullable

Optional payment message, preserved exactly. Wire allows at most four lines of 35 characters; ACH allows 10 characters; SWIFT allows 12. Only printable ASCII and newlines are accepted; backslashes and other control characters are rejected. Nonempty messages are unsupported for RTP and other rails. Missing, null, or empty means no message on create; on update omission preserves the setting and null or empty clears it. A destination change revalidates the saved or supplied message. Returns null when unset. Queued batches read current settings when initializing an offramp; initialized offramps retain their saved message on retry.

mode'PER_DEPOSIT' | 'SCHEDULED' | 'THRESHOLD'

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.
thresholdAmountstring nullable

Populated only when mode=THRESHOLD; null otherwise. Decimal amount in the source currency.

status'PENDING_WALLET' | 'ACTIVE' | 'DEACTIVATED'

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.
createdAtstring date-time
updatedAtstring date-time
deactivatedAtstring date-time nullable

ISO 8601 timestamp when the address was deactivated. null if still active.

Example response

{
  "address": "0xAbC0123456789AbCdEf0123456789AbCdEf01234",
  "source": {
    "chain": "BASE"
  },
  "offrampMessage": "Invoice 42",
  "thresholdAmount": "100.00",
  "balance": {
    "currency": "usdc",
    "amount": "100.500000"
  }
}

Changes

  • 319fa6bd5bc6Revision changes
    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status