Manage the Address Book

API Users can propose address book changes. Address book changes are subject to to the approval of the admin quorum who need to approve such programmatic proposals in their Fordefi mobile app.

Authenticate your request

Since address book changes are sensitive operations, you need to cryptographically authenticate your request, by signing it, similarly to how you authenticate Create Transaction requests. Specifically:

Pass the Access Token in the Authorization: Bearer <TOKEN> header.
Sign the request body with the API User’s private key, the public key of which you have registered with the API Signer. Use the ECDSA signature scheme over the NIST P-256 curve. The signed message comprises the API endpoint timestamp and request body. Pass the signature in a x-signature HTTP header of your POST request.

Note the different endpoint

Both when sending the request and within the signed message itself, make sure to use the correct endpoint, for example /api/v1/address-book/contacts for creating a new address book contact.

Create a new contact

To create a new contact, call the Create Contact endpoint. In the request, specify the name and the address of the new contact, the chain type of the contact (for example, evm, solana, utxo, and so on). 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 this contact should be valid for.

The following are examples of the body of the request.

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

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