Skip to content

Manage the Address Book

API Users can propose address book changes. Address book changes are subject to the approval of the admin quorum.

Workflow

  • You create a valid JSON structure and send it to the appropriate endpoint in Fordefi’s API:
    • POST a /v1/addressbook/contacts request for single contact additions.
    • POST a /v1/addressbook/contacts/batch request for bulk add address operations.
  • The API validates entries, returns submission ID or errors. You get error information only if your request has errors. In the case of a bulk add addresses request, the entire batch is rejected.
  • The system triggers mobile approval for authorized approvers.
  • After approval, the address book is updated.

Constraints

Only users with appropriate permissions can initiate bulk addition actions:

  • Traders propose addresses for Admin approval.

  • For bulk add addresses requests:

    • The batch size should not surpass 1000 entries. In case you need to add more addresses, call the endpoint several times.
    • Batch processing may take up to 30 seconds for 1000 entries.
    • API rate limits apply. Learn more.

Create a new contact

To create a new contact, call the Create Contact endpoint.

In the request, specify the following:

  • name: The name of the contact.
  • type: The type of the chain.
  • address: The address on the chain.

Optionally, if you want the contact to be valid only for specific chains (within the specified chain type) or specific assets, you can specify a list of chains (for example, evm_1, solana_mainnet, and so on) or assets for which this contact should be valid.

Since address book changes are sensitive operations, they require request signing. For example, to add a Bitcoin address to the address book:

{
    "name": "My Bitcoin Contact",
    "type": "utxo",
    "address": "1JvTPkdZPhtDR7D7qAdAJ923MzFKhmN6k4",
    "chain": "bitcoin_mainnet"
}

Control the scope of the address

An address can be scoped to a single chain, all chains of a particular type (for example, EVM), or a specific asset. For example:

{
    "name": "My EVM Contact",
    "type": "evm",
    "address": "0x3fEBb139Ba00332E0B2DE6994B0bdAA505bf318D",
    "chains": []
}

Update an existing contact

To update an existing contact, call the Edit Contact endpoint. The edit request has the same format as the creation request, above.

Abort a proposal

After an address book change has been proposed, and until it has been approved by the admin quorum, you can abort the proposal using the Abort Contact endpoint.

List contacts

You can list all contacts in your workspace using the List Contacts endpoint. This API returns contacts in all states: pending, active, and deleted. If you want to get only the active contacts you can use the states query parameter.

Bulk add addresses using the API

You can submit a batch of address book entries through the Fordefi API.

Request structure and endpoint

POST a request using a JSON structure that follows the format below to: /api/v1/addressbook/contacts/batch

  • name: The name of the contact.
  • type: The type of the chain.
  • address: The address on the chain.
  • chains: The chains the contact belongs to. If not provided, the contact will be associated with all chains.

And optionally:

  • assets_identifiers: The asset identifiers of the contact.
  • group_ids: ID of the user group to retrieve.

Here is an example request:

{
    contacts: [
        {
            "name": "My Bitcoin Contact",
            "type": "utxo",
            "address": "1JvTPkdZPhtDR7D7qAdAJ923MzFKhmN6k4",
            "chain": "bitcoin_mainnet"
        },
        {
            "name": "My Bitcoin Contact2",
            "type": "utxo",
            "address": "tb1qsn262wn3hx37eh5cnrc0uy0kru32a8q8t9vv4k",
            "chain": "bitcoin_testnet"
        }
    ]
}
Previous page
Next page