HIFI Docs

GET

orchestration-addresses

{orchestrationAddressId}

Retrieve an orchestration address

curl --request GET \
  --url https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "userId": "<string>",
  "address": "0xAbC0123456789AbCdEf0123456789AbCdEf01234",
  "source": {
    "currency": "usdc",
    "chain": "BASE"
  },
  "destination": {
    "currency": "usd",
    "externalAccountId": "<string>"
  },
  "offrampMessage": "Invoice 42",
  "mode": "PER_DEPOSIT",
  "schedule": {
    "interval": "HOURLY",
    "nextRunAt": "2023-11-07T05:31:56Z"
  },
  "thresholdAmount": "100.00",
  "status": "PENDING_WALLET",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deactivatedAt": "2023-11-07T05:31:56Z",
  "balance": {
    "currency": "usdc",
    "amount": "100.500000"
  }
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_NOT_FOUND",
  "message": "<string>",
  "fields": [
    {
      "code": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  ]
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

orchestrationAddressId

string

required

Public ID of the orchestration address.

Pattern: ^orchaddr_.+$

Response

A single orchestration address record.

An orchestration address record.

string

required

Public orchestration-address ID prefixed with orchaddr_.

userId

string

Public ID of the user that owns this orchestration address.

address

string | null

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

Example:

"0xAbC0123456789AbCdEf0123456789AbCdEf01234"

source

object

Source token + chain the address accepts.

Show child attributes

destination

object

Destination payout configuration.

Show child attributes

offrampMessage

string | null

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.

Example:

"Invoice 42"

mode

enum<string>

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.

Available options:

PER_DEPOSIT,

SCHEDULED,

THRESHOLD

schedule

object | null

Populated only when mode=SCHEDULED; null otherwise.

Show child attributes

thresholdAmount

string | null

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

Example:

"100.00"

status

enum<string>

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.

Available options:

PENDING_WALLET,

ACTIVE,

DEACTIVATED

createdAt

string<date-time>

updatedAt

string<date-time>

deactivatedAt

string<date-time> | null

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

balance

object | null

The escrow wallet's live on-chain balance of the source token. Present ONLY on the single-address GET (GET /orchestration-addresses/{orchestrationAddressId}); 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.

Show child attributes

Example:

{
  "currency": "usdc",
  "amount": "100.500000"
}

⌘I

Retrieve an orchestration address

curl --request GET \
  --url https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://production.hifi.com/v3/orchestration-addresses/{orchestrationAddressId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "userId": "<string>",
  "address": "0xAbC0123456789AbCdEf0123456789AbCdEf01234",
  "source": {
    "currency": "usdc",
    "chain": "BASE"
  },
  "destination": {
    "currency": "usd",
    "externalAccountId": "<string>"
  },
  "offrampMessage": "Invoice 42",
  "mode": "PER_DEPOSIT",
  "schedule": {
    "interval": "HOURLY",
    "nextRunAt": "2023-11-07T05:31:56Z"
  },
  "thresholdAmount": "100.00",
  "status": "PENDING_WALLET",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deactivatedAt": "2023-11-07T05:31:56Z",
  "balance": {
    "currency": "usdc",
    "amount": "100.500000"
  }
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_NOT_FOUND",
  "message": "<string>",
  "fields": [
    {
      "code": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  ]
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Overview

Endpoints

Retrieve an orchestration address

Authorizations

Path Parameters

Response