Registered Addresses

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 self_custody entry for that customer — otherwise the payout returns 422 RECIPIENT_NOT_WHITELISTED. A third_party registration does not satisfy the intercompany gate: intercompany moves funds between accounts the customer owns, so the destination must be a wallet the customer controls. For the same reason, the payout request’s own destination.recipient.attestation.custody must be self — a third_party attestation declares a change of beneficial owner and returns 422 RECIPIENT_NOT_WHITELISTED even when the address is registered as self_custody. 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. A payout that sends to another of the same customer’s own Conduit wallets is also exempt: it carries destination: { "type": "wallet", "walletId": "wlt_..." } and no recipient at all, so there is no address to register. See Send a payout. Registering an address always creates it synchronously and then screens it. Most registrations clear immediately: the POST returns 201 with status registered. When screening needs more time, the POST returns 202 with status pending_screening, and the address is resolved shortly after to either registered (usable) or suspended (blocked). A registration that screening rejects returns 409. An address in pending_screening does not yet gate an outbound intercompany payout — poll until it leaves pending_screening before relying on it there. Inbound funding behaves differently; see below.

A registration does two jobs

The same record gates money in both directions, and the two jobs have different rules:

	Outbound: intercompany payout	Inbound: funding a deposit-funded order
What it gates	`destination.recipient.address` on `POST /v2/payouts` with `purpose: intercompany`	The sending address of a transfer into an order’s funding address
Custody type accepted	`self_custody` only	`self_custody` or `third_party`
While `pending_screening`	Does not gate the payout — the payout is refused	A transfer that lands is held until the screen resolves, then credited
If not registered	`422 RECIPIENT_NOT_WHITELISTED` — nothing moves	The transfer is sent back on-chain to the sender

The inbound job is why registration matters to a customer who holds no Conduit wallet at all: it is the only gate in front of an order’s funding address. See Deposit-Funded Orders.

For inbound funding, register and send straight away. A 202 is not a reason to wait: a transfer arriving mid-screen is held rather than returned, and an order’s funding deadline is 5 minutes, so waiting out a slow screen is the likelier way to miss it. Only an address that has resolved to not-registered bounces a transfer.

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. Only a self_custody address unlocks purpose: intercompany payouts. It carries no originatorDetails, because the customer is the party on both sides — when it funds an order, the customer’s own verified identity is what the sender is screened against.
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 — and, when the address funds an order, that disclosure is the identity Conduit screens the sender against. A third_party address is screened and recorded, and it does clear inbound deposit funding, but because it names a different beneficial owner it does not satisfy the intercompany payout gate:
- entityType: "individual" → firstName, lastName, dateOfBirth, countryOfCitizenship
- entityType: "business" → legalName, country

Lifecycle

Status	Meaning
`registered`	Screened and ready to receive payouts. A registration that clears immediately returns this with `201`; one that returned `202 pending_screening` reaches it once screening clears.
`pending_screening`	Screening has not finished yet. The `POST` returned `202`; the address resolves to `registered` or `suspended` shortly after. Not usable for an outbound payout until it becomes `registered`; a transfer funding an order that arrives in this window is held, not returned.
`suspended`	Blocked. Returned as a `409` when re-registering an already-suspended address or when a registration is screened and rejected; an address can also become `suspended` when a `pending_screening` screen resolves to a rejection. A transfer arriving from a suspended address is not bounced automatically: it fails the compliance check and parks for review, and the review decides the outcome — either returned to the sending address (`returned`) or frozen in Conduit’s custody (`frozen`). Don’t retry; contact Conduit.
`revoked`	The registration was cancelled via `DELETE`. Terminal.

Re-registering an address that is already registered or pending_screening for the customer is idempotent — it returns the existing record rather than creating a duplicate.

Key fields

Field	Type	Description
`id`	`wra_*`	Unique identifier for the registered address.
`chain`	string	Chain the address is on (e.g. `ethereum`).
`address`	string	The destination address. Returned normalized (e.g. lowercased for EVM chains).
`type`	`self_custody` \| `third_party`	Custody model declared at registration.
`selfCustodyAttestation`	boolean	Present for `self_custody`; the customer attests they own the wallet.
`originatorDetails`	object \| null	Beneficial-owner disclosure for `third_party`.
`status`	see above	Current status.
`label`	string \| null	Optional human-readable label.

API surface

POST /v2/customers/:customerId/wallets/registered-addresses — register an address (requires Idempotency-Key); returns 201 registered when screening clears immediately, 202 pending_screening when it resolves asynchronously, or 409 if screening rejects
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"
  }'

Testing in sandbox

In the sandbox environment, the screening verdict is deterministic — it is driven by the address you register:

Address	Registration outcome
Exactly `0xdead000000000000000000000000000000000001` (EVM) or `TMockSanctioned9xZqWvTronAddrABCDe` (Tron), or a `third_party` registration whose originator legal name is `Acme Sanctioned LTD` or `Blocked Entity SA`	`409` — the address is persisted as `suspended` and stays barred
Starting with `0x999` (EVM), or exactly `TMockReviewPend9xZqWvTronAddrABCDe` (Tron)	`202` `pending_screening` — resolve it with the simulate endpoint below
Starting with `0x000`	`202` `pending_screening` that never resolves (the automatic re-screen fails it again every time); the simulate endpoint returns `409` for it — revoke it via `DELETE` when done
Anything else	`201` `registered`

An address parked pending_screening by the 0x999 review value is resolved self-service:

POST /v2/sandbox/wallets/registered-addresses/:id/simulate/compliance-decision with body { "outcome": "approve" | "reject" } — returns 200 with the address at its final status. approve moves it to registered and releases any deposits from that address that were waiting on its registration; reject moves it to suspended (not reversible, and re-registering the same address returns 409).

A resolved verdict never flip-flops: repeating the same decision returns 200 with the address’s current state (safe for client retries), while a conflicting decision returns 409. The magic values are checked top to bottom — a sanctioned match (address or originator name) wins over the 0x999 review prefix. The fixed Tron review value parks at most once per customer (a resolved registration replays idempotently instead of re-parking); for repeated runs use fresh 0x999 EVM addresses.

curl -X POST {{api-host}}/v2/sandbox/wallets/registered-addresses/$ADDRESS_ID/simulate/compliance-decision \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{ "outcome": "approve" }'

Getting Started

How Conduit Works

Concepts

How-To Guides

Webhooks

Overview

A registration does two jobs

Custody types

Lifecycle

Key fields

API surface

Testing in sandbox

​Overview

​A registration does two jobs

​Custody types

​Lifecycle

​Key fields

​API surface

​Testing in sandbox

Overview

A registration does two jobs

Custody types

Lifecycle

Key fields

API surface

Testing in sandbox