Skip to main content

​
Overview

A Registered Address is a crypto destination address that your organization whitelists against a customer. Registering screens the address once and records it; a crypto payout with purpose: INTERCOMPANY then requires its destination.recipient.address to match a REGISTERED entry for that customer — otherwise the payout returns 422 RECIPIENT_NOT_WHITELISTED. The registered address is a whitelist match by chain + address that gates the payout, not a recipient you reference by id: every POST /v2/payouts still carries the full destination.recipient, and there is no registeredAddressId field. For any other purpose, registering is not required — the inline recipient is accepted without a prior whitelist entry. Registration is synchronous — a successful POST returns the address already in REGISTERED status. (This differs from whitelist recipients, where bank recipients go through an asynchronous review.)

​
Custody types

A registered address declares who controls the destination wallet, set by the type discriminator:
  • SELF_CUSTODY — the customer owns and controls the wallet. Requires selfCustodyAttestation: true.
  • THIRD_PARTY — the wallet belongs to someone else (for example, a counterparty’s wallet). Requires originatorDetails describing the beneficial owner, used for Travel Rule disclosure:
    • entityType: "INDIVIDUAL" → firstName, lastName, dateOfBirth, countryOfCitizenship
    • entityType: "BUSINESS" → legalName, country

​
Lifecycle

StatusMeaning
REGISTEREDThe address has been screened and is ready to receive payouts. Returned synchronously on a successful registration.
SUSPENDEDThe registration has been temporarily suspended. Payouts to this address are blocked until it is restored. A 409 REGISTERED_ADDRESS_SUSPENDED is returned both when re-registering an already-suspended address and when a first-time registration is screened and suspended on the spot — in either case don’t retry; contact Conduit.
REVOKEDThe registration was cancelled via DELETE. Terminal.
Re-registering an address that is already REGISTERED for the customer is idempotent — it returns the existing record rather than creating a duplicate.

​
Key fields

FieldTypeDescription
idwra_*Unique identifier for the registered address.
chainstringChain the address is on (e.g. ethereum).
addressstringThe destination address. Returned normalized (e.g. lowercased for EVM chains).
typeSELF_CUSTODY | THIRD_PARTYCustody model declared at registration.
selfCustodyAttestationbooleanPresent for SELF_CUSTODY; the customer attests they own the wallet.
originatorDetailsobject | nullBeneficial-owner disclosure for THIRD_PARTY.
statussee aboveCurrent status.
labelstring | nullOptional human-readable label.

​
API surface

  • POST /v2/customers/:customerId/wallets/registered-addresses — register an address (requires Idempotency-Key); returns 201 with status: REGISTERED
  • GET /v2/customers/:customerId/wallets/registered-addresses — list registered addresses for the customer
  • GET /v2/wallets/registered-addresses/:id — get a single registered address
  • DELETE /v2/wallets/registered-addresses/:id — revoke a registered address (terminal)
curl -X POST {{api-host}}/v2/customers/$CUSTOMER_ID/wallets/registered-addresses \
  -H "x-api-key: $API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "type": "SELF_CUSTODY",
    "chain": "ethereum",
    "address": "0xRecipientAddress",
    "selfCustodyAttestation": true,
    "label": "Treasury cold wallet"
  }'