npm package: @mintology/mintology
Description: Mintology SDK for JavaScript's Nodejs Runtime.
Latest version: 0.0.5

# Mintology SDK

Mintology SDK for JavaScript's Nodejs Runtime.

## Install

NPM

```
$ npm install @mintology/mintology --save
```

Yarn

```
$ yarn add @mintology/mintology
```

## How to use

You will need to authenticate using your Mintology API Key, and also the Project ID corresponding to one of your projects.

_This SDK should always be used from your backend to prevent any potential spamming or exposing your private API key._

```js
import { Mintology } from '@mintology/mintology';

const mintology = new Mintology({
  apiKey: 'secret-api-key-from-mintology-settings',
  projectId: 'project-id-from-mintology-dashboard',
});
```

## How to configure

If you open the [Mintology Dashboard](https://dashboard.mintology.app), you can find your secret API key by clicking on your name (top-right of the screen), and selecting _API Key_. The _Project ID_ can be found in each project. Please check the source to check supported options.

- The default environment is production (`prod`), you can modify it by passing your value with `env` key. Please note that the `dev` environment uses the [Goerli Testnet](https://goerli.net/); to test paid endpoints, you can use [test credit card numbers](https://stripe.com/docs/testing).

```js
const mintology = new Mintology({
  env: 'dev',
  apiKey: 'secret-api-key-from-mintology-settings',
  projectId: 'project-id-from-mintology-dashboard',
});
```

## Available methods

These are the methods currently supported.

- [Authorize](#authorize)
- [Claim](#claim)
- [Mint](#mint)
- [Find Wallet By Email](#find-wallet-by-email)
- [Create Mintable Wallet](#create-mintable-wallet)
- [Request to Export Mintable Wallet Private Key](#request-to-export-mintable-wallet-private-key)
- [Export Mintable Wallet Private Key](#export-mintable-wallet-private-key)
- [Remove Mintable Wallet Private Key From Mintology](#remove-mintable-wallet-private-key-from-mintology)
- [Decrypt Mintable Wallet Private Key](#decrypt-mintable-wallet-private-key)

### Authorize

This method is used to check if a user owns a particular token (or any token of a particular collection). If you do not specify a contract_address, we will use the contract associated with your project. If you do not specify a token_id, we will check if the wallet contain any token from the contract.

If you know the user you want to authorise has a [Mintable](https://mintable.com) account, you can use their email, and we will automatically check their wallet.

```js
await mintology.authorize({
  email: 'example@yourorganization.com',
});
```

If you want to check a wallet address directly—without using the email address of the user—you can use `wallet_address` instead if `email`.

```js
await mintology.authorize({
  wallet_address: 'wallet-address-of-the-recipient',
});
```

These are the following attributes accepted by this method.

- `contract_address` The Contract address to check. This is the address of the NFT contract that minted the token and it is optional; if this parameter is absent, the project contract address will be used instead.
- `token_id` Token Id to check. This is the token id of the specific NFT token within the contract and it is optional; if absent, any token from the contract will authorize the wallet.
- Either of the following:
  - **`email`** The email address of the user whose wallet you want to verify
  - **`wallet_address`** The wallet address to verify

```js
await mintology.authorize({
  token_id: 'example-token-id',
  email: 'example@yourorganization.com',
  contract_address: '0xb44753fb732b70201a80f34857236bd84963825a',
});
```

These are the following response attributes.

1. `authorized` is a boolean indicating whether the claim was authorized

```typescript
{
  authorized: boolean;
}
```

### Claim

This method will mint a free NFT to your user's wallet (which can be a Mintable Wallet, or their existing crypto wallet). This is the endpoint you should use for discount coupons, proof of attendance, and in general NFTs which you do not intend to sell.

_Note: Separating the mint and claim methods will allow you to clearly identify the purpose of each call in your analytics._

```js
await mintology.claim({
  email: 'example@yourorganization.com',
});
```

If you know the wallet address of the recipient, you can use `wallet_address` instead of `email`. Example:

```js
await mintology.authorize({
  wallet_address: 'wallet-address-of-the-recipient',
});
```

These are the following attributes accepted by this method.

- `metadata` Optional metadata to associate with minted token, if you don't have a pre-minted NFT in the dashboard, you need to pass in your own metadata to use.
- Either of the following:
  - **`email`** The email address of the recipient (we'll look up the wallet address for you, or create one if required)
  - **`wallet_address`** The wallet address of the recipient

```js
await mintology.claim({
  email: 'example@yourorganization.com',
  metadata: {
    image: 'https://www.example.com/yournft.png',
    name: 'Example',
  },
});
```

These are the following response attributes.

1. `token_id` is a string indicating token id of the claimed token

```typescript
{
  token_id: string;
}
```

### Mint

This method enables the minting of an NFT directly to the user's wallet. The user's wallet can be either a Mintable Wallet or their existing crypto wallet. This is the recommended endpoint for NFTs intended for sale, airdropping to specific users, or for collectible NFTs.

_Note: Separating the mint and claim methods will allow you to clearly identify the purpose of each call in your analytics._

```js
await mintology.mint({
  email: 'example@yourorganization.com',
});
```

If you know the wallet address of the recipient, you can use `wallet_address` instead of `email`. Example:

```js
await mintology.authorize({
  wallet_address: 'wallet-address-of-the-recipient',
});
```

These are the following attributes accepted by this method.

- `metadata` Optional metadata to associate with minted token, if you don't have a preminted NFT in the dashboard, you need to pass in your own metadata to use.
- Either of the following:
  - **`email`** The email address of the recipient (we'll look up the wallet address for you, or create one if required)
  - **`wallet_address`** The wallet address of the recipient

```js
await mintology.mint({
  email: 'example@yourorganization.com',
  metadata: {
    image: 'https://www.example.com/yournft.png',
    name: 'Example',
  },
});
```

These are the following response attributes.

1. `token_id` is a string indicating token id of the minted token

```typescript
{
  token_id: string;
}
```

### Find Wallet By Email

Get the _Mintable Wallet_ address corresponding to an email address.

```js
await mintology.wallet.findByEmail({
  email: 'example@yourorganization.com',
});
```

These are the following attributes accepted by this method.

- **`email`** The email address of the owner, it is required.

These are the following response attributes.

1. `address` is an ethereum address, The wallet address linked to this user (can be a custodial or noncustodial wallet)

```typescript
{
  address: 0x${string};
}
```

### Create Mintable Wallet

Create a new Mintable Wallet, and a Mintable account. Users have the ability to claim custody of their private keys from their Mintable profile page. Please note that a username can be provided: if you do not provide a username, a random one will be generated and the user will be able to modify it from the Mintable website. This is a display name used on the site to reference the user, since the email address is confidential.

```js
await mintology.wallet.create({
  email: 'example@yourorganization.com',
});
```

These are the following attributes accepted by this method.

- **`email`** The email address of the Mintable wallet owner, it is required.
- **`username`** The display name used on the site to reference the user and it is optional; if this parameter is absent, we will generate a random username.

```js
await mintology.wallet.create({
  email: 'example@yourorganization.com',
  username: 'example_wallet_owner',
});
```

These are the following response attributes.

1. `wallet_address` is an ethereum address string, The wallet address that was created.

```typescript
{
  wallet_address: 0x${string};
}
```

### Request to Export Mintable Wallet Private Key

When a user wants to take custody of their Mintable Wallet, you can call this method to initiate the process. When you call the method, we will send an email to the user, with an OTP which will have to be provided to access the private key of the wallet. This flow ensures that the request was indeed initiated by the user, since we will be sending this email from our systems. In order to access the private key, both the OTP sent to the user, and the request ID returned by this endpoint will have to be provided.

```js
await mintology.wallet.exportPrivateKey({
  email: 'example@yourorganization.com',
  wallet_address: 'your_wallet_address',
});
```

These are the following attributes accepted by this method.

- **`email`** The email address of the Mintable wallet owner, it is required.
- **`wallet_address`** The wallet address that you want to export, it is required.

These are the following response attributes.

1. `request_id` is a string UUID, The request ID given from calling wallet export.

```typescript
{
  request_id: string;
}
```

### Export Mintable Wallet Private Key

Export the Mintable wallet private key. This method requires the request_id (which you got when calling 'Request to Export Mintable Wallet Private Key', and the OTP which was sent to the user by that endpoint—this is necessary to ensure the user gives their consent to the export.

```js
await mintology.wallet.approveExportPrivateKey({
  code: 'otp_which_was_sent_to_the_user',
  email: 'example@yourorganization.com',
  wallet_address: 'your_wallet_address',
  request_id: 'request_to_export_wallet_private_key',
});
```

These are the following attributes accepted by this method.

- **`code`** The OTP which was sent to the user, it is required.
- **`email`** The email address of the Mintable wallet owner, it is required.
- **`request_id`** You got when calling '[Request to Export Mintable Wallet Private Key](#request-to-export-mintable-wallet-private-key)', it is required.
- **`wallet_address`** The wallet address that you want to export, it is required.

These are the following response attributes.

1. `private_key` is an ethereum private key string, The private key of the Mintable wallet your requested to export.

```typescript
{
  private_key: 0x${string};
}
```

### Remove Mintable Wallet Private Key From Mintology

Once a user has taken custody of their Mintable Wallet, this permanently removes the private key from our systems. Please note that it is your responsibility to ensure the user has indeed received and safely stored their private key.

```js
await mintology.wallet.approveExportPrivateKey({
  email: 'example@yourorganization.com',
  wallet_address: 'your_wallet_address',
  private_key: 'your_wallet_private_key',
});
```

These are the following attributes accepted by this method.

- **`email`** The email address of the Mintable wallet owner, it is required.
- **`private_key`** You got when calling '[Export Mintable Wallet Private Key](#export-mintable-wallet-private-key)', it is required.
- **`wallet_address`** The wallet address that you want to export, it is required.

### Signup Mintable Users

To create a marketplace user, you can use this method.

```js
await mintology.signUp({
  email: 'example@yourorganization.com',
});
```

These are the following attributes accepted by this method.

- **`email`** The email address of the Mintable wallet owner, it is required.

## See Also

- [Mintology Docs](https://docs.mintology.app)

## License

MIT © [Mintable PTE LTD](https://mintable.com/)