Identities
Keep an address book of the people and companies you transact with, and see their names on your transactions
Identities are your organisation's address book. Each identity is a person or company you transact with, and holds their addresses on any network Treasury supports. Treasury uses your identities to show names instead of raw addresses when you build, approve, and review transactions.
Only your organisation can see its identities. io.vault keeps them off chain and doesn't share them with anyone else.
Identity types
| Type | Details |
|---|---|
individual | First and last name. Displayed as "First Last". |
corporate | Company name, registration number, and website. Displayed by company name. You can also add contacts: the people you deal with at the company. |
Both types can have an email address and a relationship to you: counterparty, investor, custodian, issuer, vendor, or partner.
Add an identity and its addresses
Create an identity with POST /v2/identities, and include its addresses in the same request:
{
"type": "corporate",
"companyName": "Example Trading Ltd",
"relationship": "counterparty",
"addresses": [
{ "chain": "ethereum", "address": "0x000000000000000000000000000000000000dEaD", "label": "Settlement" },
{ "chain": "ripple", "address": "<xrp-address>", "destinationTag": "<tag>", "label": "XRP deposits" }
]
}The identity and all its addresses are saved together, or not at all. Send an idempotency-key header so a retried request can't create a duplicate.
To add another address later, use POST /v2/identities/{identityId}/addresses.
| Address field | Notes |
|---|---|
chain | The network, such as ethereum, bitcoin, or solana. |
address | Checked against the network's address format. |
label | Optional. A name for this address, such as "Settlement". It is the only part of an address you can change later. |
destinationTag | XRP Ledger only. Optional. |
Each address can belong to only one identity per network in your organisation, including archived ones. Adding an address that's already in your address book returns 409. For EVM networks, addresses are compared without regard to letter case.
Manage identities
| Endpoint | Use |
|---|---|
GET /v2/identities | List identities. Search by name, filter by type, or find the identity that holds an exact address and chain. |
GET, PATCH /v2/identities/{identityId} | Read or update an identity. |
PATCH /v2/identities/{identityId}/addresses/{addressId} | Change an address's label. To change the address itself, add a new one and archive the old one. |
POST .../archive, POST .../unarchive | Archive or restore an identity or a single address. |
Identities and addresses are archived rather than deleted. Archived entries are hidden from lists unless you ask for them with includeArchived.
How names are shown
Wherever Treasury shows an address, it tries to name it from your organisation's point of view, in this order:
- Vault. One of your own vaults' addresses shows the vault's name, and for a derived address, its alias.
- Identity. An address in your address book shows the identity's name and the address's label.
- Principal member and network directory, if you're an io.network member. See Address book.
If nothing matches, Treasury shows the raw address. Treasury works out names each time you read them, so renaming an identity or relabelling an address changes how it appears everywhere, including on past transactions.
Transaction requests and transaction history show these names on each sender and recipient.
Updated 17 days ago