# Contacts SDK

An Android SDK for reading device contacts with Ethereum (ETH) address and ENS name support. Built for the [ethOS](https://ethereumphone.org/) ecosystem.

ETH addresses are stored in the `DATA15` field of Android's `ContactsContract`, and ENS names are stored in `SharedPreferences` — the same convention used by the ethOS Contacts app.

[![](https://camo.githubusercontent.com/3eb6d4131b294adfb3eb923edd888a23f898db8c3529553b9afaf0aea359cd14/68747470733a2f2f6a69747061636b2e696f2f762f457468657265756d50686f6e652f436f6e746163747353444b2e737667)](https://jitpack.io/#EthereumPhone/ContactsSDK)

### Setup

#### 1. Add JitPack repository

In your root `settings.gradle.kts`:

```
dependencyResolutionManagement {
    repositories {
        // ...
        maven { setUrl("https://jitpack.io") }
    }
}
```

#### 2. Add the dependency

In your module `build.gradle.kts`:

```
dependencies {
    implementation("com.github.EthereumPhone:ContactsSDK:0.1.0")
}
```

#### 3. Add permissions

Add to your `AndroidManifest.xml`:

```
<uses-permission android:name="android.permission.READ_CONTACTS" />
<!-- Only needed if you want to write ETH addresses to contacts -->
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
```

Make sure to request these permissions at runtime on Android 6.0+.

### Usage

#### Initialize

```
val contactsSDK = ContactsSDK(context)
```

#### Get all contacts

```
val contacts = contactsSDK.getContacts()

for (contact in contacts) {
    println("${contact.displayName}: ${contact.ethAddress ?: "no ETH address"}")
}
```

#### Get contacts with ETH addresses only

```
val ethContacts = contactsSDK.getContactsWithEthAddress()
```

#### Get contacts with ENS names only

```
val ensContacts = contactsSDK.getContactsWithEns()
```

#### Get contacts with any Ethereum data (ETH address or ENS)

```
val web3Contacts = contactsSDK.getContactsWithEthData()
```

#### Get a specific contact by ID

```
val contact = contactsSDK.getContactById("123")
contact?.let {
    println("Name: ${it.displayName}")
    println("ETH: ${it.ethAddress}")
    println("ENS: ${it.ensName}")
    println("Phone: ${it.phoneNumber}")
    println("Email: ${it.email}")
}
```

#### Write an ETH address to a contact

```
contactsSDK.setEthAddress(contactId = 123L, address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
```

#### Write an ENS name to a contact

```
contactsSDK.setEnsName(contactId = 123L, ensName = "vitalik.eth")
```

#### Add a new contact with ETH data

```
val newContactId = contactsSDK.addContact(
    displayName = "Vitalik Buterin",
    phoneNumber = "+1234567890",
    email = "vitalik@ethereum.org",
    ethAddress = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    ensName = "vitalik.eth"
)
```

### Contact Model

```
data class Contact(
    val contactId: String,
    val displayName: String,
    val phoneNumber: String?,
    val email: String?,
    val photoUri: String?,
    val ethAddress: String?,
    val ensName: String?
)
```

Helper properties:

* `contact.hasEthAddress` — `true` if the contact has a valid ETH address
* `contact.hasEns` — `true` if the contact has an ENS name

### How ETH data is stored

This SDK uses the same storage convention as the ethOS Contacts app:

| Data        | Storage Location                                                           |
| ----------- | -------------------------------------------------------------------------- |
| ETH Address | `ContactsContract.Data.DATA15` under `StructuredName` MIME type            |
| ENS Name    | `SharedPreferences` with key `"ENS_{contactId}"` in `"contact_prefs"` file |

If `DATA15` contains a valid ETH address (`0x` + 40 hex chars), it's parsed as an ETH address. Otherwise, if it contains a dot (e.g., `vitalik.eth`), it's treated as an ENS name.

### Github Repo:

{% embed url="<https://github.com/EthereumPhone/ContactsSDK>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.freedomfactory.io/sdks/contacts-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.