# NFT Wallets

## Create NFT Wallet

<mark style="color:green;">`POST`</mark> `https://api.nfty.dev/v1/accounts`

This endpoint creates a new NFT Wallet and returns the address so you can associate it with a user in your app. You can optionally pass in a user\_identifier (such as email or username) and we will keep track of the association as well.

#### Headers

| Name          | Type   | Description               |
| ------------- | ------ | ------------------------- |
| Authorization | string | Your authentication token |

#### Request Body

| Name             | Type   | Description                                                                                                                                                                                                                                                                          |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| user\_identifier | string | This is a unique user identifier, such as an email address, username, or user id that you want to associate with this wallet. Using an email address allows users to access this wallet via their email. It is also useful for querying the API based on your internal user id, etc. |

{% tabs %}
{% tab title="200 Wallet account created with the returned address and optionally, the user\_identifier that you passed in." %}

```
{"address":"0xfB0f5901044756FF25bcb1f91b5fc2E7b1b5c8c1",
 "user_identifier":"user@email.com"}
```

{% endtab %}

{% tab title="422 Could not create a new wallet - with error information.

error\_code:
"unavailable" means there are no on-chain wallet contracts deployed. You should try again later or increase the maximum gas you are willing to use to deploy new wallets. The system will deploy new wallet contracts in the background as needed. Please reach out if you are hitting this error frequently.

errors:
This field may show detailed information for debugging purposes." %}

```
{"error_code":"unavailable", "errors":null}
```

{% endtab %}
{% endtabs %}

#### Example Request:

```
curl --request POST \
     --url https://api.nfty.dev/v1/accounts \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer c4Vftx4kGiFYqpjM/3p4o5pgkmuthLWUNpXNlrig8EjlnSTeVgde4kEBdI1Uc1RFqWJBBRxkOmZ/QcHQXdQNjQ==' \
     --data '{
       "user_identifier": "user@email.com"
       }'
```

#### Example Response:

```
{"address":"0x7eeef5e7ba91bbf9dc548fc786526cbba716e5d4",
 "user_identifier":"user@email.com"}
```

## Get NFT Wallet Address for User

<mark style="color:blue;">`GET`</mark> `https://api.nfty.dev/v1/accounts/user/:user_identifier`

This endpoint returns the NFT wallet address for a given user\_identifier. This wallet address is needed for most other API calls that interact with the wallet. The user\_identifer must have been associated with a wallet owned by your app during creation. If you did not associate a user\_identifier, then you will not need to use this API.

#### Path Parameters

| Name             | Type   | Description                                                                                                |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| user\_identifier | string | The user\_identifier that you passed in during wallet creation. Remember to URI escape special characters. |

#### Headers

| Name          | Type   | Description               |
| ------------- | ------ | ------------------------- |
| Authorization | string | Your authentication token |

{% tabs %}
{% tab title="200 Returns the address for this user, which will be used in most other API calls." %}

```
{"address":"0xe04d1df40973172a28f37045444df49cb9d88208"}
```

{% endtab %}

{% tab title="422 Could not find an address for this user\_identifier - with error information. Make sure that the user\_identifier given is in fact associated with an NFT Wallet that your app controls." %}

```
{"error_code":"", "errors":null}
```

{% endtab %}
{% endtabs %}

#### Example Request:

```
curl --request GET \
     --url https://api.nfty.dev/v1/accounts/user/user@email%2Ecom \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer c4Vftx4kGiFYqpjM/3p4o5pgkmuthLWUNpXNlrig8EjlnSTeVgde4kEBdI1Uc1RFqWJBBRxkOmZ/QcHQXdQNjQ=='
```

#### Example Response:

```
{"address":"0x5da2770b7decc2b03487f23af148455770919f6e"}
```

## List NFT Wallet Contents

<mark style="color:blue;">`GET`</mark> `https://api.nfty.dev/v1/accounts/:address/(:contract_address)/(:token_id)`

This endpoint returns the NFT items currently in the NFT Wallet. You can optionally filter by the *contract\_address* and *token\_id* as well. The address must be associated with a wallet owned by your app.

#### Path Parameters

| Name                                      | Type    | Description                                              |
| ----------------------------------------- | ------- | -------------------------------------------------------- |
| address<mark style="color:red;">\*</mark> | string  | Address of this wallet                                   |
| contract\_address                         | string  | Optional: Contract address for the NFTs you want to show |
| token\_id                                 | integer | Optional: ID of the token you want to filter by          |

#### Query Parameters

| Name   | Type    | Description                                              |
| ------ | ------- | -------------------------------------------------------- |
| limit  | integer | How many results to return. The maximum is 30.           |
| offset | integer | The offset of the returned results. So you can paginate. |

#### Headers

| Name                                            | Type   | Description               |
| ----------------------------------------------- | ------ | ------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Your authentication token |

{% tabs %}
{% tab title="200 List of NFTs in this wallet, with metadata link information." %}

```
{
"address":"0xe04d1df40973172a28f37045444df49cb9d88208",
"assets_count": 2,
"pending_assets_count": 0,
"assets":
 [
  {"token_id":3,"contract":"0x67fc09ae09c2964b289128347d8d080028e7ecea","type":"ERC721","token_url":"https://nfty.com/3","unlockable_content":"hidden text viewable by the NFT owner, such as a url or special access code"},
  {"token_id":3,"contract":"0xf4e1074006928685a6ca3403d495f891eece7944","type":"ERC1155","token_url":"https://nfties.com/3","unlockable_content":"hidden text viewable by the NFT owner, such as a url or special access code","amount":95}
 ]
}
```

{% endtab %}

{% tab title="422 Could not list the contents of this wallet - with error information. Make sure that the address given is in fact associated with an NFT Wallet that your app controls." %}

```
{"error_code":"", "errors":null}
```

{% endtab %}
{% endtabs %}

#### Example Request:

```
curl --request GET \
     --url https://api.nfty.dev/v1/accounts/0x5da2770b7decc2b03487f23af148455770919f6e \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer c4Vftx4kGiFYqpjM/3p4o5pgkmuthLWUNpXNlrig8EjlnSTeVgde4kEBdI1Uc1RFqWJBBRxkOmZ/QcHQXdQNjQ=='
```

#### Example Response:

```
{"address":"0x5da2770b7decc2b03487f23af148455770919f6e",
 "assets_count": 4,
 "pending_assets_count": 0,
 "assets":
  [
   {"token_id":1,"contract":"0x67fc09ae09c2964b289128347d8d080028e7ecea","type":"ERC721","token_url":"https://nfty.com/1"},
   {"token_id":1,"contract":"0xf4e1074006928685a6ca3403d495f891eece7944","type":"ERC1155","token_url":"https://nfties.com/1","amount":1},
   {"token_id":2,"contract":"0xf4e1074006928685a6ca3403d495f891eece7944","type":"ERC1155","token_url":"https://nfties.com/2","amount":2},
   {"token_id":3,"contract":"0xf4e1074006928685a6ca3403d495f891eece7944","type":"ERC1155","token_url":"https://nfties.com/3","amount":5}
  ]
}
```

## List NFT Asset History

<mark style="color:blue;">`GET`</mark> `https://api.nfty.dev/v1/accounts/:address/asset_history/:contract/(:token_id)`

This endpoint returns the deposit and withdrawal history within this NFT Wallet for items from the given contract and optional token id and type. The address must be associated with a wallet owned by your app.

#### Path Parameters

| Name                                       | Type    | Description                                     |
| ------------------------------------------ | ------- | ----------------------------------------------- |
| token\_id                                  | integer | Optional: ID of the token you want to filter by |
| address<mark style="color:red;">\*</mark>  | string  | Address of this wallet                          |
| contract<mark style="color:red;">\*</mark> | string  | Contract address for the NFTs you want to show  |

#### Query Parameters

| Name   | Type    | Description                                              |
| ------ | ------- | -------------------------------------------------------- |
| type   | string  | Filter by `deposit` or `withdrawal`                      |
| limit  | integer | How many results to return. The maximum is 30.           |
| offset | integer | The offset of the returned results. So you can paginate. |

#### Headers

| Name                                            | Type   | Description               |
| ----------------------------------------------- | ------ | ------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Your authentication token |

{% tabs %}
{% tab title="200 History of the NFT deposits and withdrawals in this wallet." %}

```
[
 {"token_id":3,"type":"deposit","timestamp":"2021-08-23T12:10:46.000Z"},
 {"token_id":3,"type":"withdrawal","timestamp":"2021-08-24T11:19:46.000Z"},
 {"token_id":4,"type":"deposit","timestamp":"2021-08-25T10:29:46.000Z"}
]

or, filtered by token_id: 3

[
 {"token_id":3,"type":"deposit","timestamp":"2021-08-23T12:10:46.000Z"},
 {"token_id":3,"type":"withdrawal","timestamp":"2021-08-24T11:19:46.000Z"}
]

or, filtered by type=withdrawal

[
 {"token_id":3,"type":"withdrawal","timestamp":"2021-08-24T11:19:46.000Z"}
]
```

{% endtab %}

{% tab title="422 Could not list asset history - with error information. Make sure that the address given is in fact associated with an NFT Wallet that your app controls." %}

```
{"error_code":"", "errors":null}
```

{% endtab %}
{% endtabs %}

#### Example Request:

```
curl --request GET \
     --url https://api.nfty.dev/v1/accounts/0x5da2770b7decc2b03487f23af148455770919f6e/asset_history/0xf4e1074006928685a6ca3403d495f891eece7944 \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer c4Vftx4kGiFYqpjM/3p4o5pgkmuthLWUNpXNlrig8EjlnSTeVgde4kEBdI1Uc1RFqWJBBRxkOmZ/QcHQXdQNjQ=='
```

#### Example Response:

```
[
 {"token_id":1,"type":"deposit","amount":1,"timestamp":"2021-08-25T12:19:46.000Z"},
 {"token_id":2,"type":"deposit","amount":2,"timestamp":"2021-08-25T12:19:46.000Z"},
 {"token_id":3,"type":"deposit","amount":10,"timestamp":"2021-08-25T12:19:46.000Z"},
 {"token_id":3,"type":"withdrawal","amount":5,"timestamp":"2021-08-25T12:19:46.000Z"}
]
```