# Introduction

Everything you need to know to use, integrate, and develop on Public Mint.

Welcome to the **Public Mint documentation**! Here you'll find detailed descriptions, guides, references, and code/flow examples to get started in no time.

The Public Mint ecosystem is comprised of various components stacked in multiple layers. Here's a few suggested reads before you start.

{% content-ref url="/pages/-LlvncII4\_eeWW2s6vJS" %}
[Core Concepts](/public-mint-basics)
{% endcontent-ref %}

{% content-ref url="/pages/-Lu7x6FLGA\_PGwg3BXZV" %}
[Embed Widget](/widget/embed)
{% endcontent-ref %}

{% content-ref url="/pages/-Lu2LEa4Lsp6jAU7Rht\_" %}
[Partner setup](/partners)
{% endcontent-ref %}


# Core Concepts

Get familiar with our ecosystem's core concepts and functionalities

## Overview

Public Mint is based on a multi-layer approach that enables fiat currencies to be deployed and transacted on various supported blockchains. The Public Mint protocol - created and maintained by Public Mint - connects all layers and blockchains together, to effectively create a bridge to the traditional financial system.

{% hint style="info" %}

### Centralization vs. Decentralization

We believe **decentralization is a** **spectrum**, and that for the foreseeable future, fiat-based solutions will be subject to some form of regulation by central authorities. Our goal is to remove that complexity so that your fiat gets the same super-powers as cryptocurrencies.
{% endhint %}

Layers and components in the Public Mint ecosystem can sit anywhere in the *decentralization spectrum*. These layers work together to strike the right balance between regulatory requirements, accountability, and the benefits of a peer-to-peer, border-less, open economy.

![Main layers that make up the network.](/files/-LlwULJRCq9MMMx8zbIK)

## Public Mint Platform

The Public Mint Blockchain connects the two distinct domains: **off-chain** and **on-chain**. Operating in each domain has different scopes, requirements, and limitations. You can integrate or develop at either one alone - but the real magic happens when you use Public Mint to connect across both.

| Domain              |            Scope            | Integration |                                                                       Use Cases                                                                       |
| ------------------- | :-------------------------: | :---------: | :---------------------------------------------------------------------------------------------------------------------------------------------------: |
| Off-chain           |     <p>Fiat<br>only</p>     | Public Mint |                                                               Custody of funds, KYC/AML                                                               |
| On-chain            |       Blockchain only       |     web3    |                                                            P2P transactions, Smart Services                                                           |
| Transacting on both | Fiat-to-chain Chain-to-fiat | Public Mint | Crypto and traditional finance, programmable money, processes automation, borderless payments, and [many more](https://www.publicmint.com/use-cases). |

At the network level, Public Mint combines a traditional client-server model with a bespoke Ethereum-compatible blockchain. Our system connects with custodial partners and KYC providers (thus ensuring compliance with financial regulations), minting or burning on-chain *tokenized fiat* to match funds held in our custodial layer.

### Multi-Custodial Layer

This layer is comprised of **Custodial Partners**, licensed financial institutions that hold custody of fiat funds on a 1:1 ratio to the supply circulating on the blockchain. The system is designed so that Public Mint **never actually touches user funds**.

Custodians connect to Public Mint via APIs and a private messaging system, which  in turn allows customers to initiate deposits and withdrawals of fiat funds from/into their bank accounts, without going through exchanges.

{% hint style="info" %}
Public Mint is currently using [PrimeTrust](https://primetrust.com/) as its primary Custodian Partner. However, our system is designed to evolve into a **multi-custodial layer across** multiple jurisdictions and currencies, open to any regulated partner, so long as they meet Public Mint's requirements and agree with compliance/operating standards.
{% endhint %}

### **Blockchain** layer

Our blockchain is a bespoke implementation of Ethereum based on [Hyperledger Besu](https://www.hyperledger.org/projects/besu), an enterprise-grade Ethereum client. Although both networks remain somewhat compatible, Public Mint is completely independent from Ethereum. Most notably, our network uses a different consensus mechanism and relies on fiat instead of Ether for Gas costs. For more details, check out the [blockchain](/blockchain-1/start) section of this documentation.

Public Mint is responsible for the transactional/currency logic, as well as for deploying and maintaining the initial infrastructure of the blockchain; this includes running all validator nodes at launch. Please note, however, that opening up to other validators is part of our roadmap to further decentralising the network.

{% hint style="info" %}
If you're new to the blockchain space, we suggest you get started at [Ethereum Foundation Learn](https://www.ethereum.org/learn/). Their library of blockchain resources (focusing on Ethereum) is a one-stop shop for both complete beginners and more experienced users.
{% endhint %}

### Smart Services layer

One step up in the blockchain abstraction ladder lies the *Smart Services* layer. Smart Services is how we refer to smart contracts (both fully autonomous or controlled by individuals/companies) that add functionalities on top of our blockchain.

Public Mint handles state changes in pretty much the same way as Ethereum's Virtual Machine. This means smart contracts can be written in any Ethereum-compatible language (like [Solidity](https://solidity.readthedocs.io/en/v0.5.11/)). If you can code in Ethereum, you can start developing in Public Mint.

In addition to sending/receiving funds, you are free to build/deploy smart contracts on top of the blockchain, earning revenue from any business model you can think of - much like you would in the web.

{% hint style="warning" %}
The Public Mint blockchain is open to everyone. You don't need to ask permission or verify your identity to send/receive funds or develop services on the blockchain. However, please note that you **cannot deposit or withdraw funds** without creating a Public Mint account and passing through a KYC process.&#x20;
{% endhint %}


# Partner setup

Registering as a Partner is necessary to access advanced features.

To be able to integrate with Public Mint services and APIs you need to register your company at the Public Mint Partnership Program. This requirement allows us to collect all the information we need to get started.

1. [Register as a Partner](/partners#enroll-as-a-partner)
2. [Complete your partner account KYC](/partners#account-kyc)
3. [Obtain your API Key](/partners#3-obtain-your-api-key)

## 1.  Register as a Partner <a href="#enroll-as-a-partner" id="enroll-as-a-partner"></a>

The registration process start with you sending an email to <support@publicmint.com> indicating your desire to become a Partner of Public Mint and a brief description of the business case you want to build.

## 2. Complete your partner account KYC <a href="#account-kyc" id="account-kyc"></a>

In order to complete the account registration process, we need to verify your identity and that of your company (via a KYC/KYB process).

After you send the initial email we will contact you to go through the KYC process, requesting the necessary information. Public Mint will review the information and contact you if additional information or documentation is needed.&#x20;

As soon as that is cleared, your account will unlocked and you will be able to [generate an API Key](/partners#3-obtain-your-api-key) and start your development.

## 3. Obtain your API Key

With your account registered and the KYC process completed, you will receive a Sandbox API Key that will give you access to all of Public Mint's partner features in our sandbox environment. Use that environment to build your business integration. When you are ready to go to production, let us know through the email <support@publicmint.com> and we will kick-start the final validation phase that will end up with a production API Key that you can use with Public Mint's production environment.

With your API key in your hand, the next step is to start your integration development. Learn more  on our [Development Quick Start Guide](/api/identities).

## 4. Receiving Callbacks

When you register as partner at the Public API you must provide a webhook endpoint. This endpoint will receive any information sent from the API to a partner, like reference numbers for deposits, or the status of requests.

Some of the content notifications sent to parters are the following:

* **Deposits**
  * **status** -> When a change occurs in the deposit status;
  * **references** -> When the reference for the deposit is made available.
* **Withdrawals**
  * **status** -> When a change occurs in the withdrawal status.

The following snippet shows an example of data payload sent by our system to a partner's webhook.

```javascript
/POST 

{
  type: 'deposits',
  data: {
    reference: 'dadas3112daSAas'
  } 
}
```


# Tutorials \[WIP]

Take a Journey through Public Mint and learn by example.

### Learn by example

{% hint style="success" %}
*Ready and set? Get inspiration from the following examples to up your game and create your own flows.*
{% endhint %}

### :arrow\_right: Make fiat payments on the blockchain

Pay your network, employees, or suppliers with fiat. All it takes is [a bank transfer](/api/funding/deposit-wire).

### :arrow\_left: Receive fiat payments from the blockchain

[Withdraw your earnings](/api/funding/withdrawing) straight into your bank account, or keep your customers' funds.

### :money\_with\_wings: Use your Ethereum-compatible wallet to send fiat on the PM blockchain

[Operate straight](/blockchain-1/transacting) in the blockchain, interacting with your ERC-20 compatible wallet.

### :rocket: Launch a Smart Service

[Deploy a smart contract](/blockchain-1/transacting#more-transactions) just like you would in any Ethereum-based network.


# Create Identities

Step-by-step example to create an Identity

In this example we'll show how to use our APIs to create a valid identity that can go through the KYC process on Public Mint's services.

## **Before you start**

Public Mint's service APIs offer a series of methods that can be used to integrate with Public Mint services and blockchain. Before you start, it's recommended that you review the full documentation available online on [developers.publicmint.io](https://developers.publicmint.io/).

### **Become a Partner**

To use Public Mint's services, you need to be registered as partner and have the API Key to access the APIs. Please contact <support@publicmint.com> to apply.

### **Environments**

Public Mint has two publicly available environments that can be used by anyone: *production* and *sandbox*

#### **Production**

The Production environment is Public Mint's main environment for partners and users. It's connected to real banks and KYC verification systems.&#x20;

{% embed url="<https://api.publicmint.io>" %}

**Sandbox**

The Sandbox environment is targeted for integration development by Partners and others that want to use Public Mint's services and blockchain. It's not connected to KYC verification systems or actual banking rails.&#x20;

{% embed url="<https://api.sandbox.publicmint.io>" %}

## **Creating Identities**

Creating a new identity is as simple as making a POST request to the /identities endpoint and passing all the required information. [Read here](https://developers.publicmint.io/api/identities/kyc-for-individuals) for more details.

**Example**

{% code title="Request" %}

```bash
curl -X POST \
  https://api.sandbox.publicmint.io/identities \
  -H 'Content-Type: application/json' \
  -H 'apiKey: [MY_API_KEY]' \
  -d '{
    "name": "John Doe",
    "email": "john.doe@mycompany.com",
    "companyOfficer": false,
    "birthday": "1998-09-09",
    "gender": "Male",
    "identityType": "person",
    "address": {
        "street": "24404 Karianne Club",
        "postalCode": "98605",
        "city": "Bingen",
        "country": "US",
        "state": "WA"
    },
    "phone": {
        "number": "5015321379",
        "sms": true
    },
    "tax": {
        "idNumber": "872343907",
        "state": "WA",
        "country": "US"
    }
}'
```

{% endcode %}

{% code title="Response" %}

```javascript
{
    "id": "4da8aa4f-4a01-4bf6-a72d-a8bac268c304",
    "app_id": "3f488bf9-52c1-4236-83d2-a99caacd3dc4",
    "verification_status": "pending",
    "blocked": false,
    "status": "active",
    ...
}
```

{% endcode %}

Take note of the `id` field from the response. That is the identity unique identifier and will be used on the remaining steps.

### Upload Identity documents

The identity verification process requires the confirmation of the personal details supplied: `identity` and `address`. That is done by uploading the necessary documents and linking them to the newly created identity. Learn more [here](https://developers.publicmint.io/api/identities/documents-and-kyc).

**Example**

{% code title="Request" %}

```bash
curl -X POST \
  https://api.sandbox.publicmint.io/documents \
  -H 'Content-Length: [TOTAL_SIZE]' \
  -H 'Content-Type: multipart/form-data; boundary=--------------------------943719922750551202326880' \
  -H 'apiKey: [MY_API_KEY]' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F description=Passport \
  -F label=passport \
  -F identityId=4da8aa4f-4a01-4bf6-a72d-a8bac268c304 \
  -F documentType=Passport \
  -F documentSide=FrontSide \
  -F file=@[PATH_TO_FILE]/passport.jpeg
```

{% endcode %}

{% code title="Response" %}

```javascript
{
    "id": "2f0a3fad-3e1c-4628-a757-70aa3bfef3cd",
    "identity_id": "4da8aa4f-4a01-4bf6-a72d-a8bac268c304",
    "status": "active",
    ...
}
```

{% endcode %}

You should upload as many documents as necessary (making one POST request per document) to prove and confirm the `identity` created.

#### **Verify Identity**

With the identity created and the documents uploaded, the KYC process will start automatically. When the process ends, the identity's `verification_status` field will be updated to reflect the final result. Only identities with `verification_status` tagged as `approved` can execute fiat operations.

#### **Sandbox**

In the sandbox environment you can override the standard KYC process and do a manual approval of the identity. To do that, you must make a POST request to the `/identities/:id/sandbox-approve-kyc` endpoint. Note that this is only possible in the sandbox environment.

**Example**

{% code title="Request" %}

```bash
https://api.sandbox.publicmint.io/identities/4da8aa4f-4a01-4bf6-a72d-a8bac268c304/sandbox-approve-kyc \
  -H 'apiKey: [MY_API_KEY]'
```

{% endcode %}

{% code title="Response" %}

```javascript
{
    "message": "Identity sent for approval"
}
```

{% endcode %}


# Create a Blockchain Address

Step-by-step example of how to create a Public Mint blockchain address

In this example you'll learn how to create a valid blockchain address that can be used on Public Mint's blockchain.

## **Before you start**

Public Mint's service APIs offer a series of methods that can be used to integrate with Public Mint services and blockchain. Before you start, it's recommended that you review the full documentation available online on [developers.publicmint.io](https://developers.publicmint.io/).

## Creating Addresses

There are many ways of creating a blockchain address. In this example, we'll use **NodeJS** with the **Web3 lib** to communicate with the blockchain.

**Example**

```javascript
const Web3 = require('web3');
const provider = 'https://public.tst.publicmint.io:8545'; // Public Mint TestNet Blockchain
const opts = {
    defaultBlock: 'latest',
    transactionConfirmationBlocks: 1,
}
const web3 = new Web3(provider, null, opts);
(async function () {
   const passphrase = 'test';
   const account = await web3.eth.accounts.create(passphrase);  
   console.log('PMINT ACCOUNT address:', account.address);
   console.log('PMINT ACCOUNT PK:', account.privateKey);
})();
```

{% code title="// OUTPUT" %}

```
PMINT ACCOUNT address: 0xEa3F2eb61dD221344834eA6a3fd2128dF6641D4E
PMINT ACCOUNT PK: 0x0edd054f73c62fdca08b3940413df4f713a34cd5b702f88641b984499f165565
```

{% endcode %}

This example will return the *private key* and the *public address* of the newly created account. Both will be necessary to integrate with Public Mint's blockchain and service APIs.


# Payout Service

Step-by-step example of how to setup and use Public Mint for Payouts

In this example we'll show how to use our APIs to easily implement a payout service based on Public Mint's services and blockchain.

## **Before you start**

Public Mint's service APIs offer a series of methods that can be used to integrate with Public Mint services and blockchain. Before you start, it's recommended that you review the full documentation available online on [developers.publicmint.io](https://developers.publicmint.io/).

### **Become a Partner**

To use Public Mint's services, you need to be registered as partner and have the API Key to access the APIs. Please contact <support@publicmint.com> to apply.

### **Environments**

Public Mint has two publicly available environments that can be used by anyone: *production* and *sandbox*

#### **Production**

The Production environment is Public Mint's main environment for partners and users. It's connected to real banks and KYC verification systems.

{% embed url="<https://api.publicmint.io>" %}

**Sandbox**

The Sandbox environment is targeted for integration development by Partners and others that want to use Public Mint's services and blockchain. It's not connected to KYC verification systems or actual banking rails.&#x20;

{% embed url="<https://api.sandbox.publicmint.io>" %}

## **Creating an Address**

In order to execute payouts on the blockchain, the first step is to create and prepare an address from which the transfer will be executed. Please check out our tutorial on how to [Create a Blockchain Address](/tutorials/create-a-blockchain-address).

For this example, we'll also set up an address to be the *liquidity pool* from where payouts will be executed, and which will be replenished as funds come in via FIAT. This  allows for payouts that are effectively independent from the actual deposit of funds (within the limits of the funds preloaded into the pool).

### **Account Identity**

On Public Mint, all fiat transactions must be associated with a previously KYC-verified identity. There are three ways to obtain such an identity:

* As a **Partner**, you'll have an identity automatically created during registration, which you can use in conjunction with your API Key. Seeing as funds in the *liquidity pool* address are your own, you can use your own identity when loading funds;
* If you are using the **Public Mint Widget**, you can skip this section, as the widget will handle the identity generation automatically.
* If you prefer to have **users** provide their personal identification details to you, you can create an Identity for each of your users by forwarding that data to our API, therefore allowing your customers to deposit funds directly into an address. Please check our tutorial on how to [create identities](/tutorials/create-identities) via our API.

### **Making the First Deposit**

With an address assigned to our *liquidity pool* and an identity for deposits, you can now make a fiat deposit so that you have an initial amount available for the payout.

In this example, we'll use a bank wire transfer for the deposit. Read about other transfer methods [here](https://developers.publicmint.io/api/funding/deposit-us-ach).

**Example**

{% code title="Request" %}

```bash
curl -X POST \
  [ENVIRONMENT HOSTNAME]/deposits \
  -H 'Content-Type: application/json' \
  -H 'apikey: {INSERT API KEY HERE}' \
  -d '{
	"amount": "12",
	"currency": "USD",
	"identityId": "4da8aa4f-4a01-4bf6-a72d-a8bac268c304",
	"blockchainAddress": "0xA4597E696a55fD76430945e0940DA17c72337ccC",
	"transferInformation": {
		"transferType": "wire"
	}
}'
```

{% endcode %}

{% code title="Response" %}

```javascript
{
    "id": "cd132ff7-1f19-4144-9d92-e30fa65df2a2",
    "identity_id": "4da8aa4f-4a01-4bf6-a72d-a8bac268c304",
    "status": "waiting",
    "reference": "CUSFGRA",
    "transfer_type": "wire",
    ...
}
```

{% endcode %}

At the moment the deposit is created, the `reference` field is initially set to `null`.&#x20;

As this is an *async operation,* the response will be returned via POST request to the partner's webhook URL. Alternatively, you can make a GET request to the `/deposits/:id` endpoint, where `:id` is the id returned from the deposit POST call. Read more about it [here](https://developers.publicmint.io/api/reference/deposits).

The `reference` should then be used for making the wire transfer to Public Mint's bank account.&#x20;

{% hint style="danger" %}
Make sure to include the `reference` on the transfer description, and that the *origin account* is held by **the** **same identity you used to create the deposit**.
{% endhint %}

#### Sandbox

In the sandbox environment, you can bypass the deposit settlement process with a *manual settlement*. To do that, you need to make a POST request to the `/deposits/:id/sandbox-settle-deposit`endpoint.  Note that this is only possible in the sandbox environment.

**Example**

{% code title="Request" %}

```bash
curl -X POST \
  https://api.sandbox.publicmint.io/deposits/cd132ff7-1f19-4144-9d92-e30fa65df2a2/sandbox-settle-deposit \
  -H 'Content-Type: application/json' \
  -H 'apiKey: [MY_API_KEY]' \
  -d '{
	"amount": "50000",
	"status": "settled"
}'
```

{% endcode %}

{% code title="Response" %}

```javascript
{
    "message": "Deposit settled"
}
```

{% endcode %}

## Requesting a Payout

Now that the liquidity pool address has funds, you can request payouts from the blockchain. Doing so is as simple as making a transfer between your blockchain account and the destination account.

**Example**

```javascript
// Initialising Web3

const Web3 = require('web3');
const provider = 'https://public.tst.publicmint.io:8545'; // Public Mint TestNet Blockchain
const opts = {
    defaultBlock: 'latest',
    transactionConfirmationBlocks: 1,
}
const web3 = new Web3(provider, null, opts);

// Blockchain account address.
const address = '0xFF206CeBAC998aEC817E7fc456fc3451eEEaA860';

// Blockchain account private key.
const accountPK = '0x93bdf0a31e3069243bb7ccf65056d2d0c526deaf5f4d3d3bc78c7a163c9136e4';
const destAddress = '0xEa3F2eb61dD221344834eA6a3fd2128dF6641D4E';

// Building transaction
(async function () {
 const contract = new web3.eth.Contract(contractABI, ERC20_USDP_ADDR, {
   from: address
 });
   const account = web3.eth.accounts.privateKeyToAccount(accountPK);
   const entropy = '54674321§3456764321§345674321§3453647544±±±§±±±!!!43534534534534';
   const wallet = web3.eth.accounts.wallet.create(1, entropy);

   wallet.add(account);
   const amountToSend = web3.utils.toHex(web3.utils.toWei('10.00', 'ether'));
   const result = await contract.methods.transfer(destAddress,amountToSend).send({
     from: address
   });
   console.log(result)
})();
```

When the pool gets low on funds, all you need is to make a new deposit and you're set.


# Getting started

The Public Mint Widget allows web dApps and apps to directly receive fiat funds.

The Public Mint Widget allows any dApp or web app to directly receive funds from the network. The Widget can be configured to allow the user to choose the destination address, or to direct funds at a specific address - such as that of a smart contract - with the option of specifying which address it is depositing on behalf of.&#x20;

![](/files/-M6eVJfsihVFRolRib9i)

The widget can be used in two different ways:

* **Open**\
  Any dApp can embed our widget offering core payment methods such as wire, ACH and stablecoins. For  processes that require KYC, the process is done within the widget.<br>
* **Registered Partner**\
  Any dApp or app can [register as a Partner](/partners), which allows it to pre-fill KYC data (when applicable) and also access riskier payment methods or higher limits.

It is very simple to embed the widget, with different options available according to the platform your dApp or web app is using.


# Embed Widget

The widget can be embedded on a page within a traditional web application or on an embedded iOS/Android WebView. You can control how the widget behaves and tweak the user experience to your needs with the Javascript configuration parameters at the initialization phase.

As an integrator, you won't have direct access to the customer's personal information. The underlying personal information is exposed only in response to demands made to Public Mint lawfully (or, in some cases, in support of **security** authorization).


# Deposit of funds

As a dApp or web app that wants to integrate the Public Mint Widget to enable your users to make deposit of funds to a given address (yours or theirs), you can easily embed the widget onto your application with a simple javascript code.

Public Mint's Widget is made available through a SDK that needs to be included on your application.

### Initialisation

Initialise the SDK by creating an instance of the `PmintWidgetSdk` class:

```javascript
import PmintWidgetSdk from '@publicmint/widget-sdk';

const pmint = new PmintWidgetSdk();
```

### Deposit widget

To show the deposit widget, call the `renderAddFunds` method. This method returns a promise that resolves with either `completed` or `canceled`.

```javascript
const status = await pmint.renderAddFunds({
  blockchain: 'publicmint',
  destinationAddress: address,
  locale: 'en'
});
```

The `renderAddFunds` method requires that you pass the information necessary for the widget to know what to show the user:

* **blockchain** - the target blockchain for the funds. At this stage only we only support `publicmint` as the target blockchain.
* **destinationAddress** - the address to where the funds will be deposited. This address can be yours (ex: a liquidity pool) or your customer's address.&#x20;
* **locale** - The localization to be used by the widget.

### Example

![](/files/-M6eVJfsihVFRolRib9i)


# Withdraw of funds

As a dApp or web app that wants to integrate the Public Mint Widget to enable your users to withdraw funds from a given address (yours or theirs), you can easily embed the widget onto your application with a simple javascript code.

Public Mint's Widget is made available through a SDK that needs to be included on your application.

### Initialisation

Initialise the SDK by creating an instance of the `PmintWidgetSdk` class:

```javascript
import PmintWidgetSdk from '@publicmint/widget-sdk';

const pmint = new PmintWidgetSdk();
```

### Withdraw widget

To show the withdraw widget, call the `renderWithdraw` method. This method returns a promise that resolves with either `completed` or `canceled`.

```javascript
import { withdraw } from '@publicmint/widget-sdk';
import PublicMintWeb3 from '@publicmint/publicmint-web3';

const status = await pmint.renderWithdraw({
  blockchain: 'publicmint',
  burn: options => {
    // Perform the blockchain operation.
    // When using the public mint blockchain use our `withdraw` utility:
    const web3 = new PublicMintWeb3();
    return withdraw(web3, { ...options, privateKey });
  },
  locale: 'en',
  originAddress: address
})
```

The `renderWithdraw` method requires that you pass the information necessary for the widget to know what to show the user:

* **blockchain** - the target blockchain for the funds. At this stage only we only support `publicmint` as the target blockchain.
* **originAddress** - the address from where the funds will be taken. This address can be yours (ex: a liquidity pool) or your customer's address.&#x20;
* **locale** - The localization to be used by the widget.
* **burn** - a callback function to be used sign and submit the operation to the blockchain. It is at this stage that the address private key is need.

### Example

![](/files/-M6eVQOQqZ3SlW3TSvbW)


# Getting started

Start building your integration in minutes.

You can integrate with Public Mint via APIs only, directly on the blockchain, or across both domains. This guide takes you through all you need for a full integration, including onboarding, fiat transactions, and blockchain transactions.

| What                    | Where            | Transactions                                                                                |
| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
| Onboarding              | API              | User creation and authentication, identity creation, documents submission, KYC confirmation |
| Fiat transactions       | API / Blockchain | Deposits and withdrawals to (and from) the blockchain.                                      |
| Blockchain transactions | Blockchain       | Wallet-to-wallet transfers, smart contract deployment, smart contract calls.                |

{% hint style="info" %}
Venn diagram illustrating transaction types and where they touch/intersect: 1. Onboarding / 2. Fiat transactions / 3. Blockchain transactions
{% endhint %}

![Diagram illustrating steps: 1. Onboarding / 2. Fiat transactions / 3. Blockchain transactions](/files/-Lmx90dzWBQImzklEewG)

{% hint style="warning" %}
Integrating with the **blockchain** **alone** doesn't require any account. However, moving fiat funds on and off the blockchain is only possible with a verified account. We explain all you need to know to integrate with the blockchain in the [blockchain integrations section](/api/connecting).
{% endhint %}

## Creating your API key

Developing your integration with Public Mint starts with creating your partner account and going through an onboarding process (either on your behalf or in that of your customers). The process begins with obtaining your first API key. To be eligible to use Public Mint's APIs you need to be a verified business partner. You can learn more about how to apply at the [Partners section](/partners).

When your application is successful you'll receive a confirmation email giving you access to the Partners Portal, where you'll be able to generate, revoke and manage your API keys.&#x20;

You'll need to pass on your API key in the request headers when making calls to Public Mint's endpoints to [authenticate your requests](/api/reference/authentication#Authorization) and identify witch application/partner is using the APIs.

{% hint style="success" %}
While we work on finalizing the Partner's Portal, please contact us directly to request early access to our API.
{% endhint %}

## Public Mint API Environments

We currently have two environments you can access:  *production* and *sandbox*. Their hostnames are as follows:

| Environment | Hostname                                                       |
| ----------- | -------------------------------------------------------------- |
| Production  | [https://api.publicmint.io](https://api.sandbox.publicmint.io) |
| Sandbox     | <https://api.sandbox.publicmint.io>                            |


# Creating identities

Most API calls require an IdentityID to operate on, and there's a few ways to get one.

An identity is the core entity on Public Mint service. It represents an individual or company and is required to be able to execute most of the operations.

The creation of an identity is executed in 2 distinct steps:

1. Upload all the identity KYC documentation (ex: ID Card, proof-of-address, selfie, etc.) to Public Mint's AWS secure S3 bucket;
2. Create the identity passing the required information, including the documents uploaded from step 1.

## Step 1 - Upload KYC documents

The first step when creating an identity is to upload the KYC documents to Public Mint's AWS secure S3 bucket.&#x20;

You need to first request a pre-signed url for each of the documents to be uploaded, using the following API method:

## POST /presign-url

<mark style="color:green;">`POST`</mark> `[ENVIRONMENT_HOST]/presign-url`

Request a pre-sign url for a document to be uploaded.

#### Request Body

| Name                                       | Type   | Description                         |
| ------------------------------------------ | ------ | ----------------------------------- |
| filename<mark style="color:red;">\*</mark> | String | The name of the file to be uploaded |

{% tabs %}
{% tab title="200: OK Response with the details to be used for upload." %}

```javascript
{
    "data": {
        "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/",
        "fields": {
            "key": "f1/ad/2a/17/Q9TdlaDeAqvdwrjM.jpeg",
            "bucket": "pmint-custodial-api-sandbox-identity-docs",
            "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
            "X-Amz-Credential": "ASIAXVB7MGLQKWDL2ONQ/20220401/eu-west-1/s3/aws4_request",
            "X-Amz-Date": "20220401T101751Z",
            "X-Amz-Security-Token": "FwoGZXIvYXdzEKT//////////wEaDMSysV9GDJK8pUzCMCLaASCB2eCZORx/NJqlFlHiC5fhSKE8UM5ZzbVWHAiUUAsHJhWKXIRSfsRQAFdTkxSR/mpqtXwGcDSI8B/v8KfIcq+gi+Zr1zSycaN2NyG0e53Rg6nsFTD5Wg4PIO2DkTmknFhvEjI5PhOBcfylSc3dBhu28H8JuYE422K28dI/1a2LoGhfZBXEmTXothptBpr9+SWGWaG1ESigDdGdYa3lalSnS0jycLAPZUR4a3ZyEh3phVDPN3y/a84Zv/3UnWON29fS6+j1nk4aD11NHV/WLu0mHeL+2+uUs5RDKM+im5IGMi2R1GxPnv2bqIgYpd8VCUPEDOOX3/x3zjeTCdBBNlKZi9uM9pFwdDO1GPwjcKQ=",
            "Policy": "eyJleHBpcmF0aW9uIjoiMjAyMi0wNC0wMVQxMDozMjo1MVoiLCJjb25kaXRpb25zIjpbeyJrZXkiOiJmMS9hZC8yYS8xNy9ROVRkbGFEZUFxdmR3cmpNLmpwZWcifSx7ImJ1Y2tldCI6InBtaW50LWN1c3RvZGlhbC1hcGktc2FuZGJveC1pZGVudGl0eS1kb2NzIn0seyJYLUFtei1BbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In0seyJYLUFtei1DcmVkZW50aWFsIjoiQVNJQVhWQjdNR0xRS1dETDJPTlEvMjAyMjA0MDEvZXUtd2VzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsiWC1BbXotRGF0ZSI6IjIwMjIwNDAxVDEwMTc1MVoifSx7IlgtQW16LVNlY3VyaXR5LVRva2VuIjoiRndvR1pYSXZZWGR6RUtULy8vLy8vLy8vL3dFYURNU3lzVjlHREpLOHBVekNNQ0xhQVNDQjJlQ1pPUngvTkpxbEZsSGlDNWZoU0tFOFVNNVp6YlZXSEFpVVVBc0hKaFdLWElSU2ZzUlFBRmRUa3hTUi9tcHF0WHdHY0RTSThCL3Y4S2ZJY3ErZ2krWnIxelN5Y2FOMk55RzBlNTNSZzZuc0ZURDVXZzRQSU8yRGtUbWtuRmh2RWpJNVBoT0JjZnlsU2MzZEJodTI4SDhKdVlFNDIySzI4ZEkvMWEyTG9HaGZaQlhFbVRYb3RocHRCcHI5K1NXR1dhRzFFU2lnRGRHZFlhM2xhbFNuUzBqeWNMQVBaVVI0YTNaeUVoM3BoVkRQTjN5L2E4NFp2LzNVbldPTjI5ZlM2K2oxbms0YUQxMU5IVi9XTHUwbUhlTCsyK3VVczVSREtNK2ltNUlHTWkyUjFHeFBudjJicUlnWXBkOFZDVVBFRE9PWDMveDN6amVUQ2RCQk5sS1ppOXVNOXBGd2RETzFHUHdqY0tRPSJ9XX0=",
            "X-Amz-Signature": "2b9a7f914ce0d8aa5a16b3ae5811c4668f3714212c4f4eb34742c960729d79fb"
        }
    }
}
```

{% endtab %}
{% endtabs %}

With the response from the previous request, you can upload the file to aWS S3 bucket. Please refer to [**AWS documentation**](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-post-example.html) on how to do that.

## Step 2 - Create the identity

With the documents uploaded to the S3 bucket, the next step is create the identity on the Public Mint services, passing all the information including the uploaded documents. Refer to the [**Identities API** ](/api/reference/identities#create_an_identity)for details on how to do it.


# Connecting to the blockchain

How to connect to the Public Mint blockchain.

Integrating or building solely on the blockchain doesn't require permission from Public Mint or anybody else. You can connect to the Public Mint blockchain by remotely connecting to it and only takes a few steps.

### Web3.js and other wrappers

Developing blockchain-based applications usually requires work on two domains:

1. Smart contract development: code which gets deployed to the blockchain, written in Solidity in the case of Public Mint (and Ethereum);
2. Web or app development: code deployed on the web as an interface to read and write data from the blockchain/smart contracts.

Even though you can connect your web app directly to a client using JSON-RPC calls, you can use a wrapper to make your life easier when trying to connect the two domains and create a full-fledged interface.

![Example of diagram to illustrate stack](/files/-Lmv0Bv3IbUoag1RYekb)

Web3.js is a collection of Javascript libraries that allow you to easily perform transactions on the blockchain. This includes read/write data, send money, and even deploy smart contracts!&#x20;

{% hint style="success" %}
We use **Node.js**, **publicmint-web3.js**, and similar Javascript-based libraries throughout this documentation. However, you are free to use any language/wrapper you want.
{% endhint %}

## Getting started

Connecting to the blockchain takes just a few steps:

* [Step 1: Connect to a node](/api/connecting#step-2-connect-to-a-node)
* [Step 2: Test your connection](/api/connecting#step-3-test-your-connection)

## Step 1: Connect to a node

The Public Mint client is based on Hyperledger Besu, and likewise it includes a command line interface and JSON-RPC API for running and monitoring nodes. &#x20;

Our client also supports smart contract deployment and operational tools (such as Remix, web3.js, or MyCrypto). Apart from a [few key differences](/blockchain-1/start), the interface should be quite familiar to Ethereum developers.

{% hint style="success" %}
In our examples we'll use publicmint-web3.js, this package is a umbrella class that is building above web3.js one of the most popular Javascript libraries for Ethereum. For installation instructions, go to[ publicmint-web3.js](https://public-mint-community.gitlab.io/publicmint-web3.js/) and [web3.js](https://github.com/ethereum/web3.js/) .
{% endhint %}

Start by installing **publicmint-web3.js**. From the terminal, type:

```bash
$ mkdir myDappProject && cd $_ 
$ npm init .
$ npm install @publicmint/publicmint-web3
$ touch index.js
```

Inside `index.js` start by requiring web3:

```javascript
import PublicMint from 'publicmint-web3';

// For JS es5 use:

const PublicMint = require('publicmint-web3').default;

```

This variable will now allow you to create a connection to a Public Mint node.&#x20;

Next, it's time to connect. Depending on whether your are connecting to our TestNet (blockchain used by Public Mint Sandbox environment) or to our MainNet (Public Mint production environment), you should enter the following:

{% tabs %}
{% tab title="TestNet" %}

```javascript
const web3 = new PublicMint('testNet'); // or chainId 2019
```

{% endtab %}

{% tab title="MainNet" %}

```javascript
const web3 = new PublicMint(); // default 'mainNet' or chainId 2020
```

{% endtab %}
{% endtabs %}

See more about providers [here](https://gitlab.com/public-mint-community/publicmint-web3.js/-/blob/develop/docs/tutorials/ChooseProviders.md).

This step will create a normal web3 instance excluding modules not working for now ([excluded modules](https://www.npmjs.com/package/@publicmint/publicmint-web3)), and create a new namespace `web3.pm` that contains all contracts and basic features for interface with PublicMint client.&#x20;

Learn more about `.pm` [modules](https://public-mint-community.gitlab.io/publicmint-web3.js/).

You're almost done. Now it's time to test it.

## Step 3 - Test your connection

To make sure everything went smoothly, let's query the blockchain for the latest block:

```javascript
> web3.eth.getBlockNumber()
.then(console.log);

> 3141 // Most recent block number
```

Congratulations! You are connected to the Public Mint blockchain. Read on to go through examples of some of the operations you can perform.


# Running your own client node

A node in Public Mint is a crucial part of the network. The network operates in the bases of a Peer-to-Peer (P2P) network, thus all nodes have similar **responsibilities**, **requirements** and they need to talk to each other. Therefore, it is crucial, if you operate a Public Mint node, to follow all the guidance in this page.

### Minimum System Requirements <a href="#minimum-system-requirements" id="minimum-system-requirements"></a>

* 4GB of RAM
* 2 vCPU

For instance, in Amazon Web Services a t3.medium EC2 type fits the requirements.

#### Disk Space <a href="#disk-space" id="disk-space"></a>

Syncing Public Mint MaiNet or TestNet requires 50GB for a full sync. Thus, we recommend **50GB** of available disk space.

The disk used will tend to grow in the future, following the grow of the blockchain history. Thus, this requirement will be adjusted accordingly.

## Running Public Mint client from Binary Distribution <a href="#running-public-mint-client-from-binary-distribution" id="running-public-mint-client-from-binary-distribution"></a>

Works for Linux, Unix, Windows & macOS.

#### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* [Java JDK](https://www.oracle.com/technetwork/java/javase/downloads/index.html) (version 11 or or higher)

Public Mint client requires Java 11+; earlier versions are not supported. Public Mint client is currently supported only on 64-bit versions of Windows, and requires a 64-bit version of JDK/JRE. We recommend that you also remove any 32-bit JDK/JRE installations.

**Linux Open File Limit**

If a Too many open files RocksDB exception occurs, increase the maximum number of open files allowed using ulimit.

| **Filename**                                                                                      | **Release number** | **Release date** | **Release notes** |
| ------------------------------------------------------------------------------------------------- | ------------------ | ---------------- | ----------------- |
| [publicmint-1.0.3.zip](https://publicmint-client.s3-eu-west-1.amazonaws.com/publicmint-1.0.3.zip) | 1.0.3              | 2020/01/21       | First version     |

Unpack the downloaded files and change into the `publicmint-<release>` directory.

Display Public Mint command line help to confirm installation:

**Linux/macOS**

`bin/publicmint --help`

**Windows**

`bin\publicmint --help`

### Starting Public Mint client <a href="#starting-public-mint-client" id="starting-public-mint-client"></a>

Take into account the **minimum system requirements**.

#### Local Block Data <a href="#local-block-data" id="local-block-data"></a>

When connecting to a network other than the network previously connected to, you must either delete the local block data or use the --data-path option to specify a different data directory.

To delete the local block data, delete the database directory in the `publicmint/build/distribution/publicmint-<version>` directory.

#### Genesis Configuration <a href="#genesis-configuration" id="genesis-configuration"></a>

The client specifies the genesis configuration, and sets the network ID and bootnodes when connecting to the different Public Mint networks.

To operate your node on **PublicMint TestNet** you need to specify `--network=publicmint_testnet` to use the correct genesis configuration. To operate your node in **PublicMint MainNet** use `--network=publicmint_mainnet`

{% hint style="info" %}
**Recap**

For **TestNet** use: `--network=publicmint_testnet`\
For **MainNet** use: `--network=publicmint_mainnet`
{% endhint %}

Or you can use the **configuration file** to specify the network.

#### Configuration file <a href="#configuration-file" id="configuration-file"></a>

To specify command line options in a file, use a TOML configuration file.

The configuration file can be saved and reused across node startups. To specify the configuration file, use the --config-file option.

To override an option specified in the configuration file, specify the same option on the command line. If an option is specified in multiple places, the order of priority is command line, configuration file.

An example of a configuration file to run a Public Mint node:

```bash
data-path="~/publicmint_data" # Path to store blockchain history

# Network
network="publicmint_testnet"

# Enable HTTP and WS on 127.0.0.1 host (HTTP port: 8545, WS port: 8546)
rpc-http-enabled=true
rpc-ws-enabled=true

# Specifies domain URLs for CORS validation
# Domain URLs must be enclosed in double quotes and comma-separated
# Domains that can access the node using JSON-RPC
# If your client interacts with your client using a browser app (e.g. Remix or block explorer), you must whitelist the client domains 
rpc-http-cors-origins=["localhost", "127.0.0.1"]

# Comma-separated list of hostnames to allow access to the JSON-RPC API
# By default, access from localhost and 127.0.0.1 is accepted
host-whitelist=["localhost", "127.0.0.1"]
```

Starting client with a configuration file:

`bin/publicmint --config-file=/home/me/publicmint_node/config.toml`

The node by default is running on host 127.0.0.1 and the HTTP port is 8545 and Web Service port is 8546

#### Configuring Ports <a href="#configuring-ports" id="configuring-ports"></a>

Ports must be exposed appropriately to enable communication. An example port configuration for a node on AWS is:

![](/files/-Ly-hdjkBA0RN8SMdAnB)

30303 is the default P2P port, that can be specified using `--p2p-port`.

#### Confirm Node is Running <a href="#confirm-node-is-running" id="confirm-node-is-running"></a>

If you have started the client with the `--rpc-http-enabled` option, use cURL to call [web3\_clientVersion](https://github.com/ethereum/wiki/wiki/JSON-RPC#web3_clientversion) to confirm the node is running.

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' http://127.0.0.1:8545
```

## Running Public Mint client from Docker Image <a href="#running-public-mint-client-from-docker-image" id="running-public-mint-client-from-docker-image"></a>

A Docker image is provided to run a Public Mint node in a Docker container.

Use this Docker image to run a single Public Mint node without installing Public Mint client.

### Prerequisites <a href="#prerequisites.1" id="prerequisites.1"></a>

* [Docker](https://docs.docker.com/install/)
* MacOS or Linux

The Docker image does not run on Windows

### Starting Public Mint client <a href="#starting-public-mint-client.1" id="starting-public-mint-client.1"></a>

Take into account the **minimum system requirements**.

Available tags for the image are listed at <https://hub.docker.com/r/publicmint/client/tags>

#### Exposing Ports <a href="#exposing-ports" id="exposing-ports"></a>

Expose ports for P2P peer discovery, and HTTP and WebSockets JSON-RPC. Exposing the ports is required to use the default ports or the ports specified using --rpc-http-port, --p2p-port and --rpc-ws-port options.

To run and expose local ports for access:

```bash
docker run -p <localportJSON-RPC>:8545 -p <localportWS>:8546 -p <localportP2P>:30303 publicmint/client:latest --rpc-http-enabled --rpc-ws-enabled docker run -p <localportJSON-RPC>:8545 -p <localportWS>:8546 -p <localportP2P>:30303 publicmint/client:latest --rpc-http-enabled --rpc-ws-enabled --network=publicmint_testnet
```

**Example**

To enable JSON-RPC HTTP calls to 127.0.0.1:8545 and P2P discovery on 127.0.0.1:13001:

```bash
docker run -p 8545:8545 -p 13001:30303 publicmint/client:latest --rpc-http-enabled
```

#### Run a Node on Public Mint TestNet <a href="#run-a-node-on-public-mint-testnet" id="run-a-node-on-public-mint-testnet"></a>

{% hint style="danger" %}
**Important**

Do not mount a volume at the default data path (/opt/publicmint). Mounting a volume at the default data path interferes with the operation of the node and prevents it from safely launching.

To run a node that maintains the node state (key and database), \[--data-path] must be set to a location other than /opt/publicmint and a storage volume mounted at that location.
{% endhint %}

To run a node on TestNet with the Web Service and HTTP JSON-RPC service enabled:

```bash
docker run -p 8545:8545 -p 8546:8546 -p 30303:30303 --mount type=bind,source=/<myvolume/user/publicmint_testnet>,target=/var/lib/publicmint publicmint/client:latest --rpc-http-enabled --rpc-ws-enabled --network=publicmint_testnet --data-path=/var/lib/publicmint
```

### Stopping node and cleaning up resources <a href="#stopping-node-and-cleaning-up-resources" id="stopping-node-and-cleaning-up-resources"></a>

When you’re done running nodes, you can shut down the node container without deleting resources or you can delete the container after stopping it. Run docker container ls and docker volume ls to obtain the container and volume names.

To stop a container:

`docker stop <container-name>`

To delete a container:

`docker rm <container-name>`

## Troubleshooting

If Public Mint client is not working as expected, here are some things to check or try.

### Host Not Authorised <a href="#host-not-authorized" id="host-not-authorized"></a>

If you are receiving a Host not authorised error when attempting to access the JSON-RPC API, ensure --host-whitelist includes the host from which you are sending the RPC or \* - that allows any host to access your node JSON-RPC API.

### Peers Fail to Connect <a href="#peers-fail-to-connect" id="peers-fail-to-connect"></a>

If nodes are not communicating, ensure the required ports are open.

If your nodes are running in AWS, check you have appropriate SecurityGroups to allow access to the required ports.


# Executing Transactions

Learn how to fund and execute transactions with your Public Mint account

One of the key features of Public Mint is the ability to seamlessly move fiat funds to and from the blockchain without complicated and expensive exchanges.&#x20;

To take full advantage of it, you need to make a deposit to fund your account. Here's everything you need to know about funding, transacting, and withdrawing.

To be able to execute Bank operations (wire/ACH deposits and withdrawals) the specific operations need to be activated before being able to execute them. Please check the [operations section](/api/reference/operations) for details on how to do it.

{% content-ref url="/pages/-Lm11Er8dgLXwSS9rS3C" %}
[Depositing](/api/funding/deposit-wire)
{% endcontent-ref %}

{% content-ref url="/pages/-M-z7TC4oRTwGZtcqAAb" %}
[Wallet Transactions](/api/funding/transfer-tokens)
{% endcontent-ref %}

{% content-ref url="/pages/-Lm11qaBhXfkTQuTMlxF" %}
[Withdrawing](/api/funding/withdrawing)
{% endcontent-ref %}


# Depositing

Request a fiat deposit via API.

Now it's time to create your first deposit.&#x20;

* [Step 1: Create a deposit](/api/funding/deposit-wire#step-1-create-a-deposit)
* [Step 2: Deposit fiat using provided reference](/api/funding/deposit-wire#step-3-deposit-fiat-using-provided-refence)

## Step 1: Create a deposit

Start by creating a `POST` request to the `/transactions` [endpoint](/api/reference/transactions#create-a-new-transaction), indicating the destination address on-chain and the the identity of the entity executing the deposit. This identity will be verified upon reception of funds, to ensure it matches the underlying bank transaction.

{% tabs %}
{% tab title="Request" %}
{% code title="POST /transactions" %}

```
{
  "amount": "10",
  "code": "deposit:wire:usd",
  "currency": "USD",
  "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
  "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
  "paymentMethod": "wire"
}
```

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code title="POST /transactions" %}

```
{
  "data": {
    "addressId": "e7941059-74c6-4b3f-b029-d3aa03d1ea42",
    "amount": "10.00000000",
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "code": "deposit:wire:usd",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "currency": "USD",
    "deletedAt": null,
    "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "externalReference": "e7941059-74c6-4b3f-b029-d3aa03d1ea43",
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {
      "paymentMethod": "wire",
      "transactionDetails": {
        "bankName": "ROYAL BUSINESS BANK",
        "reference": "CUSCTW6GA",
        "swiftCode": "RBBCUS6L",
        "bankAccountName": "Prime Trust, LLC",
        "bankAccountNumber": "2030136050"
      }
    },
    "originAddress": null,
    "status": "pending",
    "transactionDetails": {
      "bankName": "ROYAL BUSINESS BANK",
      "reference": "CUSCTW6GA",
      "swiftCode": "RBBCUS6L",
      "bankAccountName": "Prime Trust, LLC",
      "bankAccountNumber": "2030136050"
    },
    "transactionHash": null,
    "type": "deposit",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Step 2: Deposit fiat using provided reference&#x20;

Using the `transactionDetails` returned by the service, simply transfer funds to the custodian's bank account. Bear in mind that wire transfers can take a few working days to clear through the traditional banking system.

Once the deposit is processed and confirmed, the update details will automatically be forwarded to Public Mint. This will programmatically trigger the minting of tokenized fiat and send the funds to the recipient user's wallet address on the Public Mint blockchain.

Congratulations! Your fiat is now available for you to transact all [across the blockchain](/blockchain-1/transacting)!


# Wallet Transactions

How to transfer tokenized fiat to other accounts using publicmint-web3.js

Transactions in the Public Mint blockchain are quite similar to Ethereum. All transactions take place through ERC-20-like smart contracts that handle the tokenised fiat. This means that checking balances, sending or receiving fiat require calls to that fiat currency's smart contract, with the default being USD.

Read on to learn your way around the basics.

{% hint style="success" %}

### What you'll need

* [Node.js](https://nodejs.org/en/download/)
* [Web3.js](https://github.com/ethereum/web3.js/)
  {% endhint %}

{% hint style="info" %}

### Important

Within the code, Public Mint uses the same monetary units as Ethereum when referring to its native tokens - ***Wei*** and ***Ether***. Even though the name is the same, for all effects these units represent **tokenized fiat** in the Public Mint ecosystem.
{% endhint %}

{% hint style="danger" %}

### Warning

Please DO NOT send funds into any of the addresses shown in this documentation as they are published on the internet, taken from the web3.js documentation. Doing so may result in the **loss of your funds**!
{% endhint %}

### Creating a wallet

If you haven't created a Public Mint [Web Wallet](/other-information/web-wallet) and don't have your own, then the first thing you need is a wallet. Start by connecting to a node - check the [previous section](/api/connecting#starting-your-node) to get the code.

After that, it's simple - instantiate a wallet and add the private key of your funded account:&#x20;

```javascript
import PublicMint from '@publicmint/publicmint-web3';
const web3 = new PublicMint();

// Instantiate wallet
const {
	wallet
} = web3.pm

// Add your first account
// 0x4389Af2E0515dDFe3453B1bD748aDfD5e2598cFd
const walletAccountPrivateKey1 = "0xba6cdfcc795484a9774eb98e756983da822ef3481b37d4ba649864e2d1ab4e5e";

wallet.add(walletAccountPrivateKey1);

const getAccountsRes = pm.wallet.accounts.getAccounts;
// [
//     '0x4389Af2E0515dDFe3453B1bD748aDfD5e2598cFd'
// ]
```

And that's it - keep your keys safe and don't show anyone.&#x20;

### Checking your balance

Let's use web3 instance to check the balance of a Public Mint address.&#x20;

{% hint style="warning" %}

### Please note

Just like Ethereum, transactions in the Public Mint blockchain can either *read* or *write* to the blockchain. While read-type transactions are free, writing (i.e. changing the state) entails fees. Ethereum fees are paid in ETH. In contrast, all fees on Public Mint are **paid in fiat**.
{% endhint %}

{% hint style="info" %}
The ERC20 token balance is mapped directly against the native token - for all effects, they are the same. While you can use the [web3 wallet method](https://web3js.readthedocs.io/en/v1.2.4/web3-eth.html#getbalance) `balanceOf`,  for performance reasons, we strongly recommend you use the JSON-RPC `getBalances`  to do it.
{% endhint %}

After instantiating web3 and create a connection to a Public Mint node, instantiate a local version of the ERC20\_USD contract:

```javascript

// Instantiate publicmint-web3 module

const PublicMint = require('@publicmint/publicmint-web3').default;
const web3 = new PublicMint('testNet');

const {
	USD
} = web3.pm.contracts.token

```

Then all you need to do is call the contract's `getBalances` method for your wallet's address.

```javascript
// Making web3 JSON-RPC getBalance method:
web3.eth.getBalance("0x407d73d8a49eeb85d32cf465507dd71d507100c1")
.then(console.log);
> "1000000000000"

// Alternatively, you can also use:
const myBalance = await web3.pm.wallet.accounts.getBalance("address in wallet");

// To get balances of all accounts in wallet:
const myBalances = await web3.pm.wallet.accounts.getBalances;

 /*
    {
        '0x4389Af2E0515dDFe3453B1bD748aDfD5e2598cFd': '0',
        '0xd2FA48924906e00069E81aaf778c4f586b5CA58B': '0'
    }
 */
```

### Sending Funds

Here is what you need to do to send funds to another Public Mint address.&#x20;

After getting a wallet and checking your balance to make sure everything is working, you can start transacting.&#x20;

Here's the full code snippet to get you through all the steps:

```javascript
// Instantiate: web3
const PublicMint from '@publicmint/publicmint-web3';
const web3 = new PublicMint(2019); // 'testNet'

// Your wallet
const {
	wallet
} = web3.pm

// Method to convert USD to native token units
const {
    toToken
} =  web3.pm.utils;

// 0x4389Af2E0515dDFe3453B1bD748aDfD5e2598cFd
const walletAccountPrivateKey1 = "0xba6cdfcc795484a9774eb98e756983da822ef3481b37d4ba649864e2d1ab4e5e";
wallet.add(walletAccountPrivateKey1);

const destinationAccount = '0x994e6a8c5F4c15FD004B6DAcb305cC1213C5503B';

// 10 USD will be converted to small unit using toToken function
const transferReceipt = 
  await web3.pm.wallet.accounts.transfer(destinationAccount, toToken(10))
 
// 
```

And that's it. To make sure it worked, you should check the balance on both accounts [as described above](/api/funding/transfer-tokens#looking-up-your-balance).

### More transactions

{% hint style="info" %}
For a comprehensive list of transactions with examples, please check the [web3.js documentation](https://web3js.readthedocs.io/en/v1.2.1/)'s list of methods.
{% endhint %}


# Withdrawing

Request a fiat withdrawal from a blockchain address.

The same requirements for depositing also apply to withdrawing fiat. Here's what you need:

* [Step 1: Verify KYC status & add transfer method](/api/funding/withdrawing#step-1-verify-user-kyc-status)
* [Step 2: Create a transfer method](#step-2-create-withdrawal-via-api-ach-wire-and-international-wire)
* [Step 3: ](/api/funding/withdrawing#step-3-create-withdrawal-via-api)[Call withdrawal function on token contract](/api/funding/withdrawing#step-2-call-withdrawal-function-on-token-contract)

## Step 1: Verify user KYC status & add transfer method

In case you haven't yet done so, start by submitting your documents [as explained here](broken://pages/-Lm11j191MUcorIZbOff#step-2-submit-documents-for-verification). If you haven't passed KYC, or if you're initiating a withdrawal on behalf of a user but are unsure about their verification status, follow [these steps to verify the identity's KYC status](broken://pages/-Lm11j191MUcorIZbOff#step-3-verify-kyc-status) now.&#x20;

If the response returns `identityConfirmed: true` you can go ahead with the flow.

## Step 2: Activate required operations

In order to use the transfer methods you will need to activate the operations. The available operations are:&#x20;

```
'deposit:wire',
'deposit:stablecoin',
'withdrawal:wire',
'withdrawal:stablecoin'
```

```
POST <hostname>/operations/activate

{
    "identityId": "{{identityId}}",
    "code": ["withdrawal:wire"]
}
```

## Step 3: Create a transfer method

To be able to execute a withdrawal you need to indicate what is the transfer method that is to be used for the transaction. As the execution is done directly on the blockchain, we require that all the destination details are previously supplied to be able to process them.

To create a new transfer method, you should make a `POST` request to the transfer method endpoint.

```
POST <hostname>/v2/transfer-methods

{
  "bankAccountName": "foobar",
  "bankAccountNumber": "GB94BARC10201530093459",
  "bankName": "Royal bank",
  "identityId": "87e5d63a-c92a-4f2f-a869-bb7119d0f0a0",
  "swiftCode": "BKBKESMMXXX" ,
  "type": "internationalWire"
}
```

This endpoint will return a response like the one below. The `id` is needed in the next step, when burning the USD in the blockchain.

{% tabs %}
{% tab title="Response" %}

```javascript
{
  "data": {
    "appId": "e86755c5-f997-443e-992c-67f2866278aa",
    "createdAt": "2022-06-09T18:08:27.604Z",
    "deletedAt": null,
    "externalReference": "76559632-442a-4a78-89e3-b4960cf0cd73",
    "id": "8471e769-5bc3-4531-a320-bdcab1ceea50",
    "identityId": "87e5d63a-c92a-4f2f-a869-bb7119d0f0a0",
    "metadata": {
      "bankName": "Royal bank",
      "swiftCode": "BKBKESMMXXX",
      "bankAccountName": "foobar",
      "bankAccountNumber": "GB94BARC10201530093459"
    },
    "type": "internationalWire",
    "updatedAt": "2022-06-09T18:08:29.211Z"
  }
}
```

{% endtab %}
{% endtabs %}

## Step 3: Call withdrawal function on token contract

For this step, start by making a call to the tokenized fiat contract requesting the burning of the tokens you want to withdraw. To do that, follow the instructions for integrating with the blockchain as explained[ in the blockchain section](/api/connecting#getting-started).&#x20;

This guide assumes you have Node.js installed, using `npm` package manager to install the `publicmint-web3.js`  as [detailed in the corresponding section](/api/connecting#step-2-connect-to-a-node). To instantiate a connection with Public Mint node, use the code below.

**Note: In November 1st, the previous withdrawal flow that used the API reference will be deprecated. To use the new flow with the Public Mint NPM,  you will need to upgrade to the version 3.0.0.**

{% tabs %}
{% tab title="REMOTE HOST" %}

```javascript
const rpcURL = "https://rpc.tst.publicmint.io:8545"
```

{% endtab %}

{% tab title="LOCAL HOST" %}

```bash
const rpcURL = "https://localhost:8545"
```

{% endtab %}
{% endtabs %}

Once you've [set up a web3 connection](/api/connecting#dependencies) to Public Mint's blockchain, run this code on your server to trigger the burning of tokens on-chain at Public Mint's token contract.

{% hint style="info" %}
The `referenceFromApi` in the example below is the `ID` of the transfer method created on the previous step. Note that you only need to create the transfer method once and use it as many times as you want.
{% endhint %}

{% tabs %}
{% tab title="Node.js" %}
{% code title="BURNING TOKENS" %}

```javascript
// Import Public Mint web3 interface.
import PublicMint from '@publicmint/publicmint-web3';

// Create web3 umbrella class with PublicMint namespace `pm`.
// By default is "ws" and <2020> - <mainNet>, only 'ws' provider it's possible listen events.
// For <testNet> or chainID <2019> and http service provider see example bellow.
// const web3 = new PublicMint(2019, "http")
const web3 = new PublicMint();

// Blockchain wallet operations.
const { wallet } = web3.pm

// Utils for hashing and convert dollar amount to small token unit "wei".
const { toToken, sha256 } =  web3.pm.utils;

// USD is the interface for ERC20 smart contract.
const { USD } = web3.pm.contracts.token

// Add blockchain account ('0x4389Af2E0515dDFe3453B1bD748aDfD5e2598cFd' as example).
const walletAccountPrivateKey1 = "0xba6cdfcc795484a9774eb98e756983da822ef3481b37d4ba649864e2d1ab4e5e"; // Add your private key.
wallet.add(walletAccountPrivateKey1);

// Withdrawals
// Withdraw 1 USD this is eq to '1000000000000000000' tokens.
const tokensToWithdraw = toToken('1');
const withdrawType = sha256('ACH');

// DEPRECATED - pmint npm < 3.0.0
// !!! SEE BELLOW MORE INFO ABOUT THIS API REFERENCE !!!
// API from Public Mint will provide a reference for each withdraw for your account.
const referenceFromApi = sha256('REF FROM API');
const receipt = await USD.withdrawWireInt(tokensToWithdraw, referenceFromApi, withdrawType).send({
    from: "0x4389Af2E0515dDFe3453B1bD748aDfD5e2598cFd",
});

// NEW FLOW - pmint npm >= 3.0.0
// The new API reference will be the UUID of the created transfer method.
const referenceFromApi = '8471e769-5bc3-4531-a320-bdcab1ceea50';
const receipt = await USD.withdrawWireInt(tokensToWithdraw, referenceFromApi, withdrawType).send({
    from: "0x4389Af2E0515dDFe3453B1bD748aDfD5e2598cFd",
});

 
```

{% endcode %}
{% endtab %}

{% tab title="Solidity function" %}
This is the `withdrawal()` function from the token smart contract that you must invoke:

```javascript

 /**
     * Withdraw method of type wire transfer for US
     * @dev Destroys `amount` tokens from `account` as msg.sender, reducing the
     * total supply for this ERC20.
     * @param amount How much to withdraw from sender balance.
     * @param ref This is an reference given by api, this value need to be on
     * blockchain logs just for tracking user actions.
     *  Emits a `Withdraw` event with the `from`, `amount`, `ref`, `feeType`.
     *  Emits a `Transfer` event with `to` set to the zero address.
     *
     * Requirements
     *
     * - `account` cannot be the zero address.
     * - `account` must have at least `amount` tokens.
     * @return bool
     */
    function withdrawWireUS(uint256 amount, string memory ref)
        public
        returns (bool)
    {
        _burn(msg.sender, amount);
        // feeType WireUS
        emit Withdraw(msg.sender, amount, ref, feeTypeWireUS);
        return true;
    }

    /**
     * Withdraw method of type wire transfer for international
     * @dev Destroys `amount` tokens from `account` as msg.sender, reducing the
     * total supply for this ERC20.
     * @param amount How much to withdraw from sender balance.
     * @param ref This is an reference given by api, this value need to be on
     * blockchain logs just for tracking user actions.
     *  Emits a `Withdraw` event with the `from`, `amount`, `ref`, `feeType`.
     *  Emits a `Transfer` event with `to` set to the zero address.
     *
     * Requirements
     *
     * - `account` cannot be the zero address.
     * - `account` must have at least `amount` tokens.
     * @return bool
     */
    function withdrawWireInt(uint256 amount, string memory ref)
        public
        returns (bool)
    {
        _burn(msg.sender, amount);
        // feeType WireInt
        emit Withdraw(msg.sender, amount, ref, feeTypeWireInt);
        return true;
    }

    /**
     * Withdraw method of type ACH transfer for US
     * @dev Destroys `amount` tokens from `account` as msg.sender, reducing the
     * total supply for this ERC20.
     * @param amount How much to withdraw from sender balance.
     * @param ref This is an reference given by api, this value need to be on
     * blockchain logs just for tracking user actions.
     *  Emits a `Withdraw` event with the `from`, `amount`, `ref`, `feeType`.
     *  Emits a `Transfer` event with `to` set to the zero address.
     *
     * Requirements
     *
     * - `account` cannot be the zero address.
     * - `account` must have at least `amount` tokens.
     * @return bool
     */
    function withdrawAchUS(uint256 amount, string memory ref)
        public
        returns (bool)
    {
        _burn(msg.sender, amount);
        // feeType AchUS
        emit Withdraw(msg.sender, amount, ref, feeTypeAchUS);
        return true;
    }

```

{% endtab %}
{% endtabs %}

If successful, the function will emit an `event`, which is then captured by Public Mint's event listener.

After that, the tokens will be burned (destroyed) by the token contract.&#x20;

**Available withdrawals:**&#x20;

* withdrawAchUS
* withdrawWireInt
* withdrawWireUS

The interface is equal for all withdraw methods has the same parameters as example above.

See [here](https://public-mint.gitlab.io/publicmint-web3.js/tutorial-Withdrawals.html) more about withdrawals methods and unique costs.


# Sandbox

The **sandbox** environment is not connected to either KYC or actual banking rails, which means that such processes are not carried out. Therefore, there are a set of sandbox-only endpoints that allow you to manually approve KYC and deposits/withdrawals. This will allow you to test your integration with full independence in development mode.

&#x20;The following endpoints are available in our sandbox:

* Approve KYC
* Settle transaction

**Note: These endpoints are only available in the sandbox environment.**

## Approve KYC

<mark style="color:green;">`POST`</mark> `https://api.sandbox.publicmint.io/sandbox/identities/approve`

This Sandbox endpoint allows you to approve the KYC process of a specific identity.

#### Request Body

| Name       | Type   | Description                          |
| ---------- | ------ | ------------------------------------ |
| identityId | String | Identity identifier. Format: `uuid`. |
| email      | String | Identity email.                      |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "message": "Identity sent to approval"
}
```

{% endtab %}
{% endtabs %}

## Settle Transaction

<mark style="color:green;">`POST`</mark> `https://api.sandbox.publicmint.io/transactions/:id/sandbox/confirm`

This Sandbox endpoint allows you to manually settle a transaction.&#x20;

#### Path Parameters

| Name                                 | Type   | Description                          |
| ------------------------------------ | ------ | ------------------------------------ |
| id<mark style="color:red;">\*</mark> | string | Id of the transaction to be settled. |

#### Request Body

| Name   | Type   | Description               |
| ------ | ------ | ------------------------- |
| amount | String | The amount to be settled. |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Deposit settled"
}
```

{% endtab %}
{% endtabs %}


# API Reference

A comprehensive guide to API resources and endpoints in the Public Mint platform

Our APIs follow the [REST architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) and present an interface familiar to most developers, using standard HTTP verbs (mostly GET, POST, PUT and DELETE) and responses.

Access to our public endpoints happens through an API gateway, where calls are [authorized and authenticated](/api/reference/authentication) before being routed to the requested resource.

In general, [errors](/api/reference/errors) return standard HTTP codes, sometimes followed by a message regarding any specific problem with the call when applicable.

You can check how to access resources via each of them in the corresponding pages.

For your reference, you can use the following Postman collection:

{% file src="/files/FWMb7foqbrIRqorWhTcl" %}


# Identities

The following endpoints are used to insert and retrieve entries representing `identities` from the database.

* [Create identity](#create-an-identity)
* [Get an identity](#get-an-identity)
* [Get an identity document presign url](#get-identity-document-presign-url)
* [Get identities](#get-identities)
* [Update an identity](#update-an-identity)
* [Delete an identity](#delete-an-identity)
* [Get operations](#get-operations)

## The `identity` object

The `identity` object represents the identity of an individual (or company) in the database.&#x20;

#### Identity entity model

| Name              |    Type    | Description                             | Constraints                 |
| ----------------- | :--------: | --------------------------------------- | --------------------------- |
| address           |  `Object`  | Address information.                    | `Not Null`                  |
| appId             |  `String`  | Application ID. Format: `uuid`.         | `Not Null`                  |
| birthday          |  `String`  | Identity birthday. Format: `Date`.      | `Between 18 and 99 years`   |
| blocked           |  `Boolean` | Identity blocked status.                | `Not Null`                  |
| createdAt         | `DateTime` | Identity created at date.               | `Not Null`                  |
| email             |  `String`  | Identity email. Format: `email`         | `Not Null`                  |
| gender            |  `String`  | Identity gender.                        | `[male, female, undefined]` |
| id                |  `String`  | Identity identifier. Format: `uuid`.    | `Not Null`                  |
| identityConfirmed |  `Boolean` | Identity with info confirmed.           | `Not Null`                  |
| identityOwner     |  `String`  | Identity company owner. Format: `uuid`. | `Nullable`                  |
| name              |  `String`  | Identity name.                          | `Not Null`                  |
| phone             |  `Object`  | Identity phone information.             | `Not Null`                  |
| tax               |  `Object`  | Identity tax information.               | `Not Null`                  |
| type              |  `String`  | Identity type.                          | `[person, company]`         |
| kycStatus         |   `Array`  | Identity kyc information.               |                             |
| updatedAt         | `DateTime` | Identity updated at date.               | `Not Null`                  |

#### Address information <a href="#user-content-address-information" id="user-content-address-information"></a>

| Name       |   Type   | Description           | Constraints                   |
| ---------- | :------: | --------------------- | ----------------------------- |
| city       | `String` | Address city.         | `Not Null`                    |
| country    | `String` | Address country code. | `Not Null`                    |
| postalCode | `String` | Address postalCode.   | `Not Null`                    |
| state      | `String` | Address state.        | `Required when country is US` |
| street     | `String` | Address street.       | `Not Null`                    |

#### Phone information <a href="#user-content-phone-information" id="user-content-phone-information"></a>

| Name   |    Type   | Description        | Constraints |
| ------ | :-------: | ------------------ | ----------- |
| number |  `String` | Phone number.      | `Not Null`  |
| sms    | `Boolean` | Available for sms. | `Not Null`  |

#### Tax information <a href="#user-content-tax-information" id="user-content-tax-information"></a>

| Name            |   Type   | Description               | Constraints                              |
| --------------- | :------: | ------------------------- | ---------------------------------------- |
| country         | `String` | Tax country code.         | `Not Null`                               |
| idNumber        | `String` | Tax id number.            | `Not Null`                               |
| state           | `String` | Tax state.                | `Required when country is US`            |
| formationRegion | `String` | Company formation region. | `Required when identity type is company` |

## Create an identity <a href="#create_an_identity" id="create_an_identity"></a>

## POST /identities

<mark style="color:green;">`POST`</mark> `[ENVIRONMENT HOSTNAME]/identities`

This endpoint allows you to create a new `identity`.&#x20;

### **Request Parameters**

None

### **Body parameters**

| Name          |       Type      | Description                             | Constraints                 |            Required           |
| ------------- | :-------------: | --------------------------------------- | --------------------------- | :---------------------------: |
| address       |     `Object`    | Address information.                    | `Not null`                  |             `true`            |
| birthday      |     `String`    | Identity birthday. Format: `Date`.      | `Between 18 and 99 years`   |  `Required if type is person` |
| documents     |     `Array`     | Identity documents.                     | `Not null`                  |                               |
| faceImages    | `Array[String]` | Identity face images. Format: `uri`     | `Not null`                  |                               |
| email         |     `String`    | Identity email. Format: `email`         | `Not null`                  |             `true`            |
| gender        |     `String`    | Identity gender                         | `[Male, Female, Undefined]` |  `Required if type is person` |
| identityOwner |     `String`    | Identity company owner. Format: `uuid`. |                             | `Required if type is company` |
| name          |     `String`    | Identity name.                          | `Not null`                  |           `Required`          |
| phone         |     `Object`    | Identity phone information.             | `Not null`                  |           `Required`          |
| tax           |     `Object`    | Identity tax information.               | `Not null`                  |           `Required`          |
| type          |     `String`    | Identity type.                          | `Not null`                  |      `[person, company]`      |

#### **Body address parameters**

| Name       |   Type   | Description         | Constraints |           Required          |
| ---------- | :------: | ------------------- | ----------- | :-------------------------: |
| city       | `String` | Address city.       | `Not null`  |            `true`           |
| country    | `String` | Address country.    | `Not null`  |            `true`           |
| postalCode | `String` | Address postal code | `Not null`  |            `true`           |
| state      | `String` | Address state       | `Not null`  | `Required if country is US` |
| street     | `String` | Address street.     | `Not null`  |          `Required`         |

#### **Body documents parameters**

| Name        |   Type   | Description                | Constraints                                                               | Required |
| ----------- | :------: | -------------------------- | ------------------------------------------------------------------------- | :------: |
| description | `String` | Document description.      |                                                                           |          |
| label       | `String` | Document label.            |                                                                           |          |
| side        | `String` | Document side.             | `[FrontSide, BackSide]`                                                   |  `true`  |
| type        | `String` | Document type              | `[DriverLicense,IdentityCard,Other,Passport,ResidencePermit,UtilityBill]` |  `true`  |
| url         | `String` | DocumentUrl. Format: `uri` | `Not null`                                                                |  `true`  |

#### **Body phone parameters**

| Name   |   Type   | Description        | Constraints | Required |
| ------ | :------: | ------------------ | ----------- | :------: |
| number | `String` | Phone number.      | `Not null`  |          |
| sms    | `String` | Available for sms. |             |          |

#### **Body tax parameters**

| Name            |   Type   | Description               | Constraints |            Required           |
| --------------- | :------: | ------------------------- | ----------- | :---------------------------: |
| country         | `String` | Tax country code.         | `Not null`  |             `true`            |
| idNumber        | `String` | Tax id number.            | `Not null`  |             `true`            |
| state           | `String` | Tax state.                | `Not null`  |  `Required if country is US`  |
| formationRegion | `String` | Company formation region. | `Not null`  | `Required if type is company` |

### **Response Options**

**400 Bad Request**

* validation\_failed
  * If the required parameters are not provided.
  * If additional parameters are provided.
  * If some of the parameters type is invalid.
  * If some of the parameters constraints is not respected.
* email\_already\_in\_use

**404 Not Found**

* identity\_owner\_not\_found
  * If a non existent identity owner `id` is provided.

**422 Unprocessable entity**

* identity\_owner\_must\_be\_of\_type\_person
  * If identity owner is not of type person.

**200 OK**

### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
POST [ENVIRONMENT HOSTNAME]/identities

{
  "address": {
    "city": "Braga",
    "country": "PT",
    "postalCode": "4444-333",
    "state": "Braga",
    "street": "Avenida D. João I,  40"
  },
  "birthday": "2000-11-11",
  "email": "foobar@publicmint.com",
  "gender": "Male",
  "name": "João Pedro Soares",
  "phone": {
    "number": "910000000",
    "sms": false
  },
  "tax": {
    "country": "PT",
    "idNumber": "1111111111",
    "state": "Braga"
  },
  "type": "person",
  "documents": [{
    "description": "ID card",
    "label": "id card",
    "side": "FrontSide",
    "type": "IdentityCard",
    "url": "https://[pmint_aws_s3_bucket].s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
  }],
  "faceImages": ["https://[pmint_aws_s3_bucket].s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"]
}
```

{% endtab %}

{% tab title="CURL" %}

```bash
curl --location --request POST 'https://api.sandbox.publicmint.io/identities' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address": {
    "city": "Braga",
    "country": "PT",
    "postalCode": "4444-333",
    "state": "Braga",
    "street": "Avenida D. João I,  40"
  },
  "birthday": "2000-11-11",
  "email": "foobar@publicmint.com",
  "gender": "Male",
  "name": "João Pedro Soares",
  "phone": {
    "number": "910000000",
    "sms": false
  },
  "tax": {
    "country": "PT",
    "idNumber": "1111111111",
    "state": "Braga"
  },
  "type": "person",
  "documents": [{
    "description": "ID card",
    "label": "id card",
    "side": "FrontSide",
    "type": "IdentityCard",
    "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
  }],
  "faceImages": ["https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"]
}
'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "data": {
        "documents": [
            {
                "createdAt": "2022-03-31T13:08:52.049Z",
                "deletedAt": null,
                "description": "ID card",
                "id": "bfca84a4-3e52-4a7d-92da-b17c6a5e59ac",
                "identityId": "38882f21-ce8f-4e18-8b83-e43e082912ef",
                "label": "id card",
                "side": "frontSide",
                "type": "identityCard",
                "updatedAt": "2022-03-31T13:08:52.049Z",
                "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
            },
            {
                "createdAt": "2022-03-31T13:08:52.114Z",
                "deletedAt": null,
                "description": null,
                "id": "0b12e957-5643-4943-9eeb-6755c02721e0",
                "identityId": "38882f21-ce8f-4e18-8b83-e43e082912ef",
                "label": null,
                "side": "frontSide",
                "type": "faceImage",
                "updatedAt": "2022-03-31T13:08:52.114Z",
                "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
            }
        ],
        "address": {
            "city": "Braga",
            "state": "Braga",
            "street": "Avenida D. João I,  40",
            "country": "PT",
            "postalCode": "4444-333"
        },
        "appId": "80937bc6-9578-45c8-b691-ea6b8a5d17e9",
        "birthday": "2000-11-11",
        "blocked": false,
        "createdAt": "2022-03-31T13:08:52.030Z",
        "email": "foobar@publicmint.com",
        "gender": "Male",
        "id": "38882f21-ce8f-4e18-8b83-e43e082912ef",
        "identityConfirmed": false,
        "identityOwner": null,
        "name": "João Pedro Soares",
        "phone": {
            "sms": false,
            "number": "910000000"
        },
        "tax": {
            "state": "Braga",
            "country": "PT",
            "idNumber": "1111111111"
        },
        "type": "person",
        "updatedAt": "2022-03-31T13:08:52.030Z"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
On the **Sandbox** environment, you can use the [approve KYC ](/api/sandbox#approve-kyc)endpoint to simulate and approve or reject the identity you created.
{% endhint %}

## Get an identity

## GET /identities/:id

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]/identities/:id`

This endpoint retrieves and returns an `identity` owned by you from the database.

### **Request Parameters**

#### **Path parameters**

| Name |   Type   | Description                          | Constraints | Required |
| ---- | :------: | ------------------------------------ | ----------- | :------: |
| id   | `String` | Identity identifier. Format: `uuid`. |             |  `true`  |

### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/identities/38882f21-ce8f-4e18-8b83-e43e082912ef
```

{% endtab %}

{% tab title="CURL" %}

```
curl --location --request GET 'https://api.sandbox.publicmint.io/identities/38882f21-ce8f-4e18-8b83-e43e082912ef' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "data": {
        "address": {
            "city": "Braga",
            "state": "Braga",
            "street": "Avenida D. João I,  40",
            "country": "PT",
            "postalCode": "4444-333"
        },
        "appId": "80937bc6-9578-45c8-b691-ea6b8a5d17e9",
        "birthday": "2000-11-11",
        "blocked": false,
        "createdAt": "2022-03-31T13:08:52.030Z",
        "email": "foobar@publicmint.com",
        "gender": "Male",
        "id": "38882f21-ce8f-4e18-8b83-e43e082912ef",
        "identityConfirmed": false,
        "identityOwner": null,
        "name": "João Pedro Soares",
        "phone": {
            "sms": false,
            "number": "910000000"
        },
        "tax": {
            "state": "Braga",
            "country": "PT",
            "idNumber": "1111111111"
        },
        "type": "person",
        "updatedAt": "2022-03-31T13:08:52.030Z"
    }
}
```

{% endtab %}
{% endtabs %}

## Get identities

## GET /identities

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]/identities`

This endpoint returns a paginated list of all `identities` owned by you.

#### **Available filters**

| Name          |       Type       | Example                              |
| ------------- | :--------------: | ------------------------------------ |
| appId         |     `default`    | `filter[appId]=foobar`               |
| blocked       |     `default`    | `filter[blocked]=true`               |
| email         |  `default,like`  | `filter[email]=like:@publicmint.com` |
| id            |   `id, default`  | `filter[id]=in:foobar`               |
| identityOwner |   `in,default`   | `filter[identityOwner]=biz`          |
| name          |     `default`    | `filter[name]=fred`                  |
| riskRating    | `in,nin,default` | `filter[riskRating]=nin:foo,bar`     |
| type          |     `default`    | `filter[type]=person`                |

#### **Available sorts**

| Name      | Example                                                            |
| --------- | ------------------------------------------------------------------ |
| createdAt | <p><code>sort=createdAt</code><br><code>sort=-createdAt</code></p> |
| updatedAt | <p><code>sort=updatedAt</code><br><code>sort=-updatedAt</code></p> |

#### **Paginate options**

| Name   | Description                                             | Example          |
| ------ | ------------------------------------------------------- | ---------------- |
| size   | Defines the number of results per page. Default = 30.   | `page[size]=2`   |
| number | Defines the number of the page to retrieve. Default = 1 | `page[number]=2` |
| all    | Return all identities without pagination                | `all=true`       |

### **Response Options**

**200 OK**

### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/identities

// PAGINATED

GET [ENVIRONMENT HOSTNAME]/identities?page[number]=1&page[size]=1
```

{% endtab %}

{% tab title="CURL" %}

```bash
curl --location --request GET 'https://api.sandbox.publicmint.io/identities' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "data": [
        {
            "address": {
                "city": "Braga",
                "state": "Braga",
                "street": "Avenida D. João I,  40",
                "country": "PT",
                "postalCode": "4444-333"
            },
            "appId": "80937bc6-9578-45c8-b691-ea6b8a5d17e9",
            "birthday": "2000-11-11",
            "blocked": false,
            "createdAt": "2022-03-31T13:08:52.030Z",
            "email": "foobar@publicmint.com",
            "gender": "Male",
            "id": "38882f21-ce8f-4e18-8b83-e43e082912ef",
            "identityConfirmed": false,
            "identityOwner": null,
            "name": "João Pedro Soares",
            "phone": {
                "sms": false,
                "number": "910000000"
            },
            "tax": {
                "state": "Braga",
                "country": "PT",
                "idNumber": "1111111111"
            },
            "type": "person",
            "updatedAt": "2022-03-31T13:08:52.030Z"
        }
    ],
    "total": 1
}
```

{% endtab %}
{% endtabs %}

## Get identity document presign url

Returns a presign url to view a specific identity document.

## GET /identities/:identityId/documents/:id/presign-url

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]identities/:identityId/documents/:id/presign-url`

This endpoint returns a paginated list of all `identities` owned by you.**Available filtersAvailable sorts**

### **Path parameters**

<table><thead><tr><th width="206">Name</th><th width="216" align="center">Type</th><th>Description</th><th>Constraints</th><th align="center">Required</th></tr></thead><tbody><tr><td>identityId</td><td align="center"><code>String</code></td><td>Identity identifier. Format: <code>uuid</code>.</td><td></td><td align="center"><code>true</code></td></tr><tr><td>id</td><td align="center"><code>String</code></td><td>Document identifier.Format: <code>uuid</code>.</td><td></td><td align="center"><code>true</code></td></tr></tbody></table>

### **Response Options**

**200 OK**

### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/identities/:identityId/documents/:id/presign-url

```

{% endtab %}

{% tab title="CURL" %}

```bash
curl --location --request GET 'https://api.sandbox.publicmint.io/identities/38882f21-ce8f-4e18-8b83-e43e082912ef/documents/2fe368e4-38ea-4329-bd2c-f8785d92ee57/presign-url' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "data": {
        "presignUrl": "https://ik.imagekit.io/p7reuy1mvbpd/aws-prod/2021/11/06/12/1c05077d-ad00-49c0-94de-4323ed8f9ad5/rn_image_picker_lib_temp_239e3a8b-6129-4d14-8fe7-ed9565cfc204.jpg"
    }
}
```

{% endtab %}
{% endtabs %}

## Update an identity

## PATCH /identities/:id

<mark style="color:purple;">`PATCH`</mark> `[ENVIRONMENT_HOSTNAME]/identities/:id`

Updates the identity information.

### **Path parameters**

<table><thead><tr><th width="330">Name</th><th width="324" align="center">Type</th><th>Description</th><th>Constraints</th><th align="center">Required</th></tr></thead><tbody><tr><td>id</td><td align="center"><code>String</code></td><td>Identity identifier. Format: <code>uuid</code>.</td><td></td><td align="center"><code>true</code></td></tr></tbody></table>

### **Request Parameters**

#### **Body parameters**

| Name          |       Type      | Description                             | Constraints                 | Required |
| ------------- | :-------------: | --------------------------------------- | --------------------------- | :------: |
| address       |     `Object`    | Address information.                    | `Not null`                  |          |
| birthday      |     `String`    | Identity birthday. Format: `Date`.      | `Between 18 and 99 years`   |          |
| documents     |     `Array`     | Identity documents.                     | `Not null`                  |          |
| email         |     `String`    | Identity email. Format: `email`         | `Not null`                  |          |
| faceImages    | `Array[String]` | Identity face images. Format: `uri`     | `Not null`                  |          |
| gender        |     `String`    | Identity gender                         | `[Male, Female, Undefined]` |          |
| identityOwner |     `String`    | Identity company owner. Format: `uuid`. |                             |          |
| name          |     `String`    | Identity name.                          | `Not null`                  |          |
| phone         |     `Object`    | Identity phone information.             | `Not null`                  |          |
| tax           |     `Object`    | Identity tax information.               | `Not null`                  |          |
| type          |     `String`    | Identity type.                          | `Not null`                  |          |

*Note: Fields name, birthday, gender, tax.country and tax.idNumber can't be updated if identity is already confirmed (identityConfirmed = true)*

#### **Body address parameters**

| Name       |   Type   | Description         | Constraints |           Required          |
| ---------- | :------: | ------------------- | ----------- | :-------------------------: |
| city       | `String` | Address city.       | `Not null`  |            `true`           |
| country    | `String` | Address country.    | `Not null`  |            `true`           |
| postalCode | `String` | Address postal code | `Not null`  |            `true`           |
| state      | `String` | Address state       | `Not null`  | `Required if country is US` |
| street     | `String` | Address street.     | `Not null`  |          `Required`         |

#### **Body documents parameters**

| Name        |   Type   | Description                | Constraints                                                               | Required |
| ----------- | :------: | -------------------------- | ------------------------------------------------------------------------- | :------: |
| description | `String` | Document description.      |                                                                           |          |
| label       | `String` | Document label.            |                                                                           |          |
| side        | `String` | Document side.             | `[FrontSide, BackSide]`                                                   |  `true`  |
| type        | `String` | Document type              | `[DriverLicense,IdentityCard,Other,Passport,ResidencePermit,UtilityBill]` |  `true`  |
| url         | `String` | DocumentUrl. Format: `uri` | `Not null`                                                                |  `true`  |

#### **Body phone parameters**

| Name   |   Type   | Description        | Constraints | Required |
| ------ | :------: | ------------------ | ----------- | :------: |
| number | `String` | Phone number.      | `Not null`  |          |
| sms    | `String` | Available for sms. |             |          |

#### **Body tax parameters**

| Name            |   Type   | Description               | Constraints |            Required           |
| --------------- | :------: | ------------------------- | ----------- | :---------------------------: |
| country         | `String` | Tax country code.         | `Not null`  |             `true`            |
| idNumber        | `String` | Tax id number.            | `Not null`  |             `true`            |
| state           | `String` | Tax state.                | `Not null`  |  `Required if country is US`  |
| formationRegion | `String` | Company formation region. | `Not null`  | `Required if type is company` |

### **Response Options**

**400 Bad Request**

* validation\_failed
  * If the required parameters are not provided.
  * If additional parameters are provided.
  * If some of the parameters type is invalid.
  * If some of the parameters constraints is not respected.
* email\_already\_in\_use

**404 Not Found**

* identity\_owner\_not\_found
  * If a non existent identity owner `id` is provided.

**422 Unprocessable entity**

* identity\_owner\_must\_be\_of\_type\_person
  * If identity owner is not of type person.

**200 OK**

### **Example Call**

{% tabs %}
{% tab title="Request" %}

```json
PATCH [ENVIRONMENT HOSTNAME]/identities/38882f21-ce8f-4e18-8b83-e43e082912ef

{
  "address": {
    "city": "Braga",
    "country": "PT",
    "postalCode": "4444-333",
    "state": "Braga",
    "street": "Avenida D. João I,  40"
  },
  "birthday": "2000-11-11",
  "email": "foobar@publicmint.com",
  "gender": "Male",
  "name": "João Pedro Soares",
  "phone": {
    "number": "910000000",
    "sms": false
  },
  "tax": {
    "country": "PT",
    "idNumber": "1111111111",
    "state": "Braga"
  },
  "documents": [{
    "description": "ID card",
    "label": "id card",
    "side": "FrontSide",
    "type": "IdentityCard",
    "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
  }],
  "faceImages": ["https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"]
}js
```

{% endtab %}

{% tab title="CURL" %}

```shell
curl --location --request PATCH 'https://api.sandbox.publicmint.io/identities/38882f21-ce8f-4e18-8b83-e43e082912ef' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address": {
    "city": "Braga",
    "country": "PT",
    "postalCode": "4444-333",
    "state": "Braga",
    "street": "Avenida D. João I,  40"
  },
  "birthday": "2000-11-11",
  "email": "foobar@publicmint.com",
  "gender": "Male",
  "name": "João Pedro Soares",
  "phone": {
    "number": "910000000",
    "sms": false
  },
  "tax": {
    "country": "PT",
    "idNumber": "1111111111",
    "state": "Braga"
  },
  "documents": [{
    "description": "ID card",
    "label": "id card",
    "side": "FrontSide",
    "type": "IdentityCard",
    "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
  }],
  "faceImages": ["https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"]
}'
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "data": {
        "documents": [
            {
                "createdAt": "2022-03-31T15:17:56.812Z",
                "deletedAt": null,
                "description": "ID card",
                "id": "d25be7eb-510b-4400-ae10-45991a9ebd86",
                "identityId": "38882f21-ce8f-4e18-8b83-e43e082912ef",
                "label": "id card",
                "side": "frontSide",
                "type": "identityCard",
                "updatedAt": "2022-03-31T15:17:56.812Z",
                "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
            },
            {
                "createdAt": "2022-03-31T15:17:56.823Z",
                "deletedAt": null,
                "description": null,
                "id": "1e802b4b-4f89-49f6-ae8a-6e1ebc731dfb",
                "identityId": "38882f21-ce8f-4e18-8b83-e43e082912ef",
                "label": null,
                "side": "frontSide",
                "type": "faceImage",
                "updatedAt": "2022-03-31T15:17:56.823Z",
                "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
            }
        ],
        "address": {
            "city": "Braga",
            "state": "Braga",
            "street": "Avenida D. João I,  40",
            "country": "PT",
            "postalCode": "4444-333"
        },
        "appId": "80937bc6-9578-45c8-b691-ea6b8a5d17e9",
        "birthday": "2000-11-11",
        "blocked": false,
        "createdAt": "2022-03-31T13:08:52.030Z",
        "email": "foobar@publicmint.com",
        "gender": "Male",
        "id": "38882f21-ce8f-4e18-8b83-e43e082912ef",
        "identityConfirmed": false,
        "identityOwner": null,
        "name": "João Pedro Soares",
        "phone": {
            "sms": false,
            "number": "910000000"
        },
        "tax": {
            "state": "Braga",
            "country": "PT",
            "idNumber": "1111111111"
        },
        "type": "person",
        "updatedAt": "2022-03-31T15:17:56.711Z"
    }
}
```

{% endtab %}
{% endtabs %}

## Get operations

#### `GET /identities/:id/operations`

Returns a list of all enabled operations for the active KYC providers and the current status of each one, depending on the KYC status of the identity.

**Request Parameters**

**Path parameters**

| Name |   Type   | Description                          | Constraints | Required |
| ---- | :------: | ------------------------------------ | ----------- | :------: |
| id   | `String` | Identity identifier. Format: `uuid`. |             |  `true`  |

**Response Options**

**200 OK**

Request example:

```
GET <hostname>/identities/e7941059-74c6-4b3f-b029-d3aa03d1ea44/operation
```

Response example:

```
{
  "data": [{
    "action": "create",
    "active": false,
    "code": "deposit:wire",
    "reason": "kyc_required_status_not_reached"
  }, {
    "action": "create",
    "active": true,
    "code": "deposit:stablecoin"
  }, {
    "action": "create",
    "active": false,
    "code": "withdrawal:wire",
    "reason": "operation_not_active_due_to_extra_kyc_missing"
  }, {
    "action": "confirm",
    "active": false,
    "code": "withdrawal:stablecoin",
    "reason": "identity_kyc_is_missing"
  }]
}
```

## Delete an identity

## DELETE /identities/:id

<mark style="color:red;">`DELETE`</mark> `[ENVIRONMENT_HOSTNAME]/identities/:id`

Deletes the identity with the given `Id`.

### **Path parameters**

| Name |   Type   | Description                          | Constraints | Required |
| ---- | :------: | ------------------------------------ | ----------- | :------: |
| id   | `String` | Identity identifier. Format: `uuid`. |             |  `true`  |

### **Response Options**

**400 Bad Request**

* validation\_failed
  * If an invalid identity `id` is provided.

**404 Not Found**

* identity\_not\_found
  * If a non existent identity `id` is provided.&#x20;

**204 OK**

### **Example Call**

{% tabs %}
{% tab title="Request" %}

```json
DELETE [ENVIRONMENT HOSTNAME]/identities/38882f21-ce8f-4e18-8b83-e43e082912ef
```

{% endtab %}

{% tab title="CURL" %}

```shell
curl --location --request DELETE 'https://api.sandbox.publicmint.io/identities/38882f21-ce8f-4e18-8b83-e43e082912ef' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm'
```

{% endtab %}
{% endtabs %}


# Operations

### Table of contents:

* `POST /operations/validate`
* `POST /operations/activate`

### Introduction <a href="#user-content-introduction" id="user-content-introduction"></a>

This API provides operations management functionalities.

### Operations <a href="#user-content-operations" id="user-content-operations"></a>

#### `POST /operations/validate` <a href="#user-content-post-operationsvalidate" id="user-content-post-operationsvalidate"></a>

Validate operation for a certain identity.

**Request Parameters**

**Path parameters**

| Name       |   Type   | Description       | Constraints                                                                            | Required |
| ---------- | :------: | ----------------- | -------------------------------------------------------------------------------------- | :------: |
| action     | `String` | Operation action. | Enum: \[`create`,`confirm`,`cancel`]                                                   |  `true`  |
| code       | `String` | Operation code.   | Enum: \[`deposit:wire`,`deposit:stablecoin`,`withdrawal:wire`,`withdrawal:stablecoin`] |  `true`  |
| identityId | `String` | Identity id.      |                                                                                        |  `true`  |

**Response Options**

**204 OK**

Request example:

```
POST <hostname>/operations/validate
```

Request example:

```
{
  "action": "create",
  "code": "deposit:wire",
  "identityId": "b0287254-df04-4793-8fbe-afa844150c91"
}
```

***

#### `POST /operations/activate` <a href="#user-content-post-operationsactivate" id="user-content-post-operationsactivate"></a>

Activate operation for a certain identity.

**Request Parameters**

**Path parameters**

| Name       |   Type   | Description     | Constraints                                                                            | Required |
| ---------- | :------: | --------------- | -------------------------------------------------------------------------------------- | :------: |
| code       | `String` | Operation code. | Enum: \[`deposit:wire`,`deposit:stablecoin`,`withdrawal:wire`,`withdrawal:stablecoin`] |  `true`  |
| identityId | `String` | Identity id.    |                                                                                        |  `true`  |

**Response Options**

**204 OK**

Request example:

```
POST <hostname>/operations/validate
```

Request example:

```
{
  "code": "deposit:wire",
  "identityId": "b0287254-df04-4793-8fbe-afa844150c91"
}
```


# Transfer Methods

The following endpoints are use to manage and retrieve the transfer methods on the system.

* `DELETE /transfer-methods/:id`
* `GET /transfer-methods/:id`
* `GET /transfer-methods`
* `POST /transfer-methods`

## Introduction <a href="#user-content-introduction" id="user-content-introduction"></a>

This API provides transfer method management functionalities.

### Transfer methods <a href="#user-content-transfer-methods" id="user-content-transfer-methods"></a>

#### Transfer method entity model <a href="#user-content-transfer-method-entity-model" id="user-content-transfer-method-entity-model"></a>

| Name              |    Type    | Description                                    | Constraints                                |
| ----------------- | :--------: | ---------------------------------------------- | ------------------------------------------ |
| appId             |  `String`  | Application ID. Format: `uuid`.                |                                            |
| createdAt         | `DateTime` | Transfer method created at date.               | `Not Null`                                 |
| deletedAt         | `DateTime` | Transfer method deleted at date.               |                                            |
| externalReference |  `String`  | Transfer method external reference.            |                                            |
| id                |  `String`  | Transfer method identifier. Format: `uuid`.    | `Not Null`                                 |
| identityId        |  `String`  | Transfer method identity owner. Format: `uuid` |                                            |
| metadata          |  `Object`  | Transfer method metadata.                      |                                            |
| type              |  `String`  | Transfer method type.                          | Enum:\[`ach`, `internationalWire`, `wire`] |
| updatedAt         | `DateTime` | Transfer method updated at date.               | `Not Null`                                 |

### Remove a transfer method

`DELETE /transfer-methods/:id`

Delete transfer method by id.

**Response Options**

**400 Bad Request**

* validation\_failed
  * If id is invalid.

**404 Not Found**

* transfer\_method\_not\_found

**204 OK**

Request example:

```
DELETE <hostname>/transfer-methods/e7941059-74c6-4b3f-b029-d3aa03d1ea44
```

### Get a transfer method

`GET /transfer-methods/:id`

Get transfer method by id.

**Response Options**

**400 Bad Request**

* validation\_failed
  * If id is invalid.

**404 Not Found**

* transfer\_method\_not\_found

**200 OK**

Request example:

```
GET <hostname>/transfer-methods/e7941059-74c6-4b3f-b029-d3aa03d1ea44
```

Response example:

```
{
  "data": {
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "deletedAt": null,
    "externalReference": null,
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {
      "bankName": "Royal bank",
      "swiftCode": "BKBKESMMXXX",
      "bankAccountName": "foobar",
      "bankAccountNumber": "GB94BARC10201530093459"
    },
    "type": "internationalWire",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }
}
```

### Get all transfer methods

`GET /transfer-methods`

Get transfer methods list.

**Available filters**

| Name              |       Type       | Example                            |
| ----------------- | :--------------: | ---------------------------------- |
| externalReference | `default,in,nin` | `filter[externalReference]=foobar` |
| id                | `default,in,nin` | `filter[id]=foobar`                |
| identityId        | `default,in,nin` | `filter[identityId]=foobar`        |
| type              | `default,in,nin` | `filter[type]=in:foobar`           |

**Available sorts**

| Name      | Example                                                            |
| --------- | ------------------------------------------------------------------ |
| createdAt | <p><code>sort=createdAt</code><br><code>sort=-createdAt</code></p> |
| updatedAt | <p><code>sort=updatedAt</code><br><code>sort=-updatedAt</code></p> |

**Paginate options**

| Name   | Description                                             | Example          |
| ------ | ------------------------------------------------------- | ---------------- |
| size   | Defines the number of results per page. Default = 30.   | `page[size]=2`   |
| number | Defines the number of the page to retrieve. Default = 1 | `page[number]=2` |
| all    | Return all identities without pagination                | `all=true`       |

**Response Options**

**200 OK**

Request example:

```
GET <hostname>/transfer-methods
```

Response example:

```
{
  "data": [{
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "deletedAt": null,
    "externalReference": null,
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {
      "bankName": "Royal bank",
      "swiftCode": "BKBKESMMXXX",
      "bankAccountName": "foobar",
      "bankAccountNumber": "GB94BARC10201530093459"
    },
    "type": "internationalWire",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }],
  "total": 1
}
```

### Create a new transfer method

`POST /transfer-methods`

Creates a transfer method.

**Request Parameters**

**Body parameters for type internationalWire**

| Name              |   Type   | Description                             | Constraints         | Required |
| ----------------- | :------: | --------------------------------------- | ------------------- | :------: |
| bankAccountName   | `String` | Bank account name amount.               | `Not null`          |  `true`  |
| bankAccountNumber | `String` | Bank account number.                    | Valid IBAN          |  `true`  |
| bankName          | `String` | Bank name.                              | `Not null`          |  `true`  |
| identityId        | `String` | Identity identification. Format: `uuid` |                     |  `true`  |
| swiftCode         | `String` | Swift code.                             | Valid swift code.   |  `true`  |
| type              | `String` | Transfer method.                        | `internationalWire` |  `true`  |

**Body parameters for type wire**

| Name              |   Type   | Description                             | Constraints              | Required |
| ----------------- | :------: | --------------------------------------- | ------------------------ | :------: |
| bankAccountName   | `String` | Bank account name amount.               | `Not null`               |  `true`  |
| bankAccountNumber | `String` | Bank account number.                    | Valid US acccount number |  `true`  |
| identityId        | `String` | Identity identification. Format: `uuid` |                          |  `true`  |
| routingNumber     | `String` | Routing number.                         | Valid routing number.    |  `true`  |
| type              | `String` | Transfer method.                        | `wire`                   |  `true`  |

**Body parameters for type ach**

| Name             |   Type   | Description                             | Constraints | Required |
| ---------------- | :------: | --------------------------------------- | ----------- | :------: |
| plaidAccessToken | `String` | Plaid access token.                     | `Not null`  |  `true`  |
| plaidAccountId   | `String` | Plaid account id.                       | `Not null`  |  `true`  |
| identityId       | `String` | Identity identification. Format: `uuid` |             |  `true`  |
| type             | `String` | Transfer method.                        | `ach`       |  `true`  |

**Body parameters for type pix**

| Name       |   Type   | Description                             | Constraints | Required |
| ---------- | :------: | --------------------------------------- | ----------- | :------: |
| document   | `String` | Document id.                            | `Not null`  |  `true`  |
| identityId | `String` | Identity identification. Format: `uuid` |             |  `true`  |
| type       | `String` | Transfer method.                        | `pix`       |  `true`  |

**Response Options**

**400 Bad Request**

* validation\_failed
  * If the required parameters are not provided.
  * If additional parameters are provided.
  * If some of the parameters type is invalid.
  * If some of the parameters constraints is not respected.

**200 OK**

Request example:

```
POST <hostname>/transfer-methods

{
  "bankAccountName": "foobar",
  "bankAccountNumber": "GB94BARC10201530093459",
  "bankName": "Royal bank",
  "identityId": "87e5d63a-c92a-4f2f-a869-bb7119d0f0a0",
  "swiftCode": "BKBKESMMXXX" ,
  "type": "internationalWire"
}
```

Response example:

```
{
  "data": {
    "appId": "e86755c5-f997-443e-992c-67f2866278aa",
    "createdAt": "2022-06-09T18:08:27.604Z",
    "deletedAt": null,
    "externalReference": "76559632-442a-4a78-89e3-b4960cf0cd73",
    "id": "8471e769-5bc3-4531-a320-bdcab1ceea50",
    "identityId": "87e5d63a-c92a-4f2f-a869-bb7119d0f0a0",
    "metadata": {
      "bankName": "Royal bank",
      "swiftCode": "BKBKESMMXXX",
      "bankAccountName": "foobar",
      "bankAccountNumber": "GB94BARC10201530093459"
    },
    "type": "internationalWire",
    "updatedAt": "2022-06-09T18:08:29.211Z"
  }
}
```


# Transactions

The following endpoints are use to create and retrieve transactions from the system.

* [Get the list of all transactions](#get-the-list-of-all-transactions)
* [Get one specific transaction](#get-one-specific-transaction)
* [Create a new transaction](#create-a-new-transaction)

## The `transaction` object

The `transaction` object represents an operation (deposit or withdrawal) executed by it's identity owner.

#### Transaction entity model

<table><thead><tr><th width="230">Name</th><th width="150" align="center">Type</th><th>Description</th><th>Constraints</th></tr></thead><tbody><tr><td>amount</td><td align="center"><code>String</code></td><td>Transaction amount.</td><td><code>Not Null</code></td></tr><tr><td>appId</td><td align="center"><code>String</code></td><td>Application ID. Format: <code>uuid</code>.</td><td></td></tr><tr><td>code</td><td align="center"><code>String</code></td><td>Transaction code.</td><td>Enum:[<code>deposit:stablecoin:usdc</code>, <code>deposit:wire:usd</code>]</td></tr><tr><td>createdAt</td><td align="center"><code>DateTime</code></td><td>Transaction created at date.</td><td><code>Not Null</code></td></tr><tr><td>currency</td><td align="center"><code>String</code></td><td>Transaction currency.</td><td>Enum:[<code>USD</code>]</td></tr><tr><td>deletedAt</td><td align="center"><code>DateTime</code></td><td>Transaction deleted at date.</td><td></td></tr><tr><td>destinationAddress</td><td align="center"><code>String</code></td><td>Transaction destination address.</td><td></td></tr><tr><td>addressId</td><td align="center"><code>String</code></td><td>Transaction address id.</td><td></td></tr><tr><td>externalReference</td><td align="center"><code>String</code></td><td>Transaction external reference.</td><td></td></tr><tr><td>id</td><td align="center"><code>String</code></td><td>Transaction identifier. Format: <code>uuid</code>.</td><td><code>Not Null</code></td></tr><tr><td>identityId</td><td align="center"><code>String</code></td><td>Transaction identity owner. Format: <code>uuid</code></td><td></td></tr><tr><td>metadata</td><td align="center"><code>Object</code></td><td>Transaction metadata.</td><td></td></tr><tr><td>originAddress</td><td align="center"><code>String</code></td><td>Transaction origin address.</td><td></td></tr><tr><td>status</td><td align="center"><code>String</code></td><td>Transaction status.</td><td>Enum:[<code>pending</code>, <code>approved</code>, <code>confirmed</code>, <code>failed</code>, <code>canceled</code>, <code>review</code>]</td></tr><tr><td>transactionHash</td><td align="center"><code>String</code></td><td>Transaction hash.</td><td></td></tr><tr><td>type</td><td align="center"><code>String</code></td><td>Transaction type.</td><td>Enum:[<code>deposit</code>, <code>transfer</code>, <code>withdrawal</code>]</td></tr><tr><td>updatedAt</td><td align="center"><code>DateTime</code></td><td>Transaction updated at date.</td><td><code>Not Null</code></td></tr></tbody></table>

## Get the list of all transactions

`GET /transactions`

Get transactions list.

**Available filters**

| Name                |       Type       | Example                              |
| ------------------- | :--------------: | ------------------------------------ |
| addressId           |     `default`    | `filter[addressId]=foobar`           |
| code                | `default,in,nin` | `filter[code]=in:foobar`             |
| currency            | `default,in,nin` | `filter[currency]=nin:foobar`        |
| destinationAddress  | `default,in,nin` | `filter[destinationAddress]=foobar`  |
| earnDistributionId  |     `default`    | `filter[earnDistributionId]=foobar`  |
| id                  | `default,in,nin` | `filter[id]=foobar`                  |
| identityId          | `default,in,nin` | `filter[identityId]=foobar`          |
| originAddress       | `default,in,nin` | `filter[originAddress]=foobar`       |
| originTransactionId |     `default`    | `filter[originTransactionId]=foobar` |
| status              | `default,in,nin` | `filter[status]=in:foobar`           |
| transactionHash     | `default,in,nin` | `filter[transactionHash]=in:foobar`  |
| type                | `default,in,nin` | `filter[type]=in:foobar`             |

**Available sorts**

| Name      | Example                                                            |
| --------- | ------------------------------------------------------------------ |
| createdAt | <p><code>sort=createdAt</code><br><code>sort=-createdAt</code></p> |
| updatedAt | <p><code>sort=updatedAt</code><br><code>sort=-updatedAt</code></p> |

**Available includes**

| Name    | Example           |
| ------- | ----------------- |
| address | `include=address` |

**Paginate options**

| Name   | Description                                             | Example          |
| ------ | ------------------------------------------------------- | ---------------- |
| size   | Defines the number of results per page. Default = 30.   | `page[size]=2`   |
| number | Defines the number of the page to retrieve. Default = 1 | `page[number]=2` |
| all    | Return all identities without pagination                | `all=true`       |

**Response Options**

**200 OK**

Request example:

```
GET <hostname>/transactions
```

Response example:

```
{
  "data": [{
    "addressId": null,
    "amount": "10.00000000",
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "code": "deposit:internal:usd",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "currency": "USD",
    "deletedAt": null,
    "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "earnDistributionId": null,
    "externalReference": null,
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {},
    "originAddress": null,
    "status": "pending",
    "transactionHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
    "type": "deposit",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }],
  "total": 1
}
```

## Get one specific transaction

`GET /transactions/:id`

Get transaction by id.

**Available includes**

| Name    | Example           |
| ------- | ----------------- |
| address | `include=address` |

**Response Options**

**400 Bad Request**

* validation\_failed
  * If id is invalid.

**404 Not Found**

* transaction\_not\_found

**200 OK**

Request example:

```
GET <hostname>/transactions/e7941059-74c6-4b3f-b029-d3aa03d1ea44
```

Response example:

```
{
  "data": {
    "addressId": null,
    "amount": "10.00000000",
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "code": "deposit:internal:usd",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "currency": "USD",
    "deletedAt": null,
    "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "earnDistributionId": null,
    "externalReference": null,
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {},
    "originAddress": null,
    "status": "pending",
    "transactionHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
    "type": "deposit",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }
}
```

## Create a new transaction

`POST /transactions`

Creates a transaction.

**Request Parameters**

**Body parameters**

| Name               |   Type   | Description                                | Constraints                                                                | Required |
| ------------------ | :------: | ------------------------------------------ | -------------------------------------------------------------------------- | :------: |
| amount             | `String` | Transaction amount.                        | `Not null`                                                                 |  `true`  |
| chain              | `String` | Transaction chain.                         | \[`ALGO`,`AVAX`,`ETH`,`SOL`,`TRX`,`XLM`]. Only for stablecoin transactions |          |
| code               | `String` | Transaction code.                          | \[`deposit:stablecoin:usdc`,`deposit:wire:usd`]                            |  `true`  |
| currency           | `String` | Transaction currency                       | \[`USD`]                                                                   |  `true`  |
| destinationAddress | `String` | Transaction destination address.           |                                                                            |  `true`  |
| identityId         | `String` | Transaction identity owner. Format: `uuid` |                                                                            |  `true`  |
| originAddress      | `String` | Transaction origin address.                |                                                                            |          |
| paymentMethod      | `String` | Transaction payment method.                | \[`wire`,`internationalWire`]. Only for Wire transactions                  |          |

**Response Options**

**400 Bad Request**

* validation\_failed
  * If the required parameters are not provided.
  * If additional parameters are provided.
  * If some of the parameters type is invalid.
  * If some of the parameters constraints is not respected.

**422 Unprocessable Entity**

* chain\_is\_not\_available
  * If the request chain is not active.

**200 OK**

Request example:

```
POST <hostname>/transactions

{
  "amount": "10",
  "chain": "XLM",
  "code": "deposit:stablecoin:usdc",
  "currency": "USD",
  "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
  "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44"
}
```

Response example:

```
{
  "data": {
    "addressId": "e7941059-74c6-4b3f-b029-d3aa03d1ea42",
    "amount": "10.00000000",
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "code": "deposit:stablecoin:usdc",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "currency": "USD",
    "deletedAt": null,
    "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "externalReference": null,
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {
      "addressId": "e7941059-74c6-4b3f-b029-d3aa03d1ea42",
      "transactionDetails": {
        "address": "0x99c7656ec7ab88b098defb751b7401b5f6d8976f",
        "addressTag": "xyyz"
      }
    },
    "originAddress": null,
    "status": "pending",
    "transactionDetails": {
      "address": "0x99c7656ec7ab88b098defb751b7401b5f6d8976f",
      "addressTag": "xyyz"
    },
    "transactionHash": null,
    "type": "deposit",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }
}
```

Request example:

```
POST <hostname>/transactions

{
  "amount": "10",
  "code": "deposit:wire:usd",
  "currency": "USD",
  "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
  "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
  "paymentMethod": "wire"
}
```

Response example:

```
{
  "data": {
    "addressId": "e7941059-74c6-4b3f-b029-d3aa03d1ea42",
    "amount": "10.00000000",
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "code": "deposit:wire:usd",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "currency": "USD",
    "deletedAt": null,
    "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "externalReference": "e7941059-74c6-4b3f-b029-d3aa03d1ea43",
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {
      "paymentMethod": "wire",
      "transactionDetails": {
        "bankName": "ROYAL BUSINESS BANK",
        "reference": "CUSCTW6GA",
        "swiftCode": "RBBCUS6L",
        "bankAccountName": "Prime Trust, LLC",
        "bankAccountNumber": "2030136050"
      }
    },
    "originAddress": null,
    "status": "pending",
    "transactionDetails": {
      "bankName": "ROYAL BUSINESS BANK",
      "reference": "CUSCTW6GA",
      "swiftCode": "RBBCUS6L",
      "bankAccountName": "Prime Trust, LLC",
      "bankAccountNumber": "2030136050"
    },
    "transactionHash": null,
    "type": "deposit",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }
}
```


# Withdrawals (deprecated)

{% hint style="danger" %}
These endpoints are deprecated and will be discontinued by November 1st. Please make sure you migrate your implementation to the new [withdrawals flow](/api/funding/withdrawing).
{% endhint %}

The following endpoints are used to insert and retrieve entries representing `withdrawals` from the database.

{% tabs %}
{% tab title="WITHDRAWALS ENDPOINTS" %}

```
POST /withdrawals
POST /withdrawals/:id/submit
GET /withdrawals/:id
GET /withdrawals
```

{% endtab %}
{% endtabs %}

## The `withdrawal` object

The `withdrawal` object represents a request for withdrawing fiat from the blockchain. You can create or retrieve an `identityId`'s withdrawals via request to the API. Or, if you manage multiple identities in the network, you can also retrieve a list of withdrawals for all of them.

Withdrawals are identified by a unique, random `id`, and relate to a user's `identityId`.

{% tabs %}
{% tab title="WITHDRAWAL OBJECT" %}

```javascript
{
    "id": "2642dedd-4fa0-40bf-8b15-7c0513bcdb38",
    "identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
    "transactionReference": "0xf6cce2d20d2714fa7be8e1bb8b8cf0abbb12ca3d34d000073742a4da954c1be5",
    "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
    "amount": null,
    "currency": "USD",
    "transactionHash": null,
    "transferInformation": {
        "transferType": "wire",
		    "bankAccountName": "Jonh do bank",
		    "bankAccountNumber": "1321312312321312",
		    "routingNumber": "123456789"
    },
    "status": "prepared",
    "createdAt": "2020-02-19T11:43:04.553Z",
    "updatedAt": "2020-02-19T11:43:04.553Z"
}
```

{% endtab %}
{% endtabs %}

## POST /withdrawals

<mark style="color:green;">`POST`</mark> `[ENVIRONMENT HOSTNAME]/withdrawals`

This endpoint allows you to add a new `withdrawal` to the database. If all the params are valid, a new record will be inserted in the database with the `withdrawal` information. \
\
**This will return a transaction reference that needs to be provided to the transaction when performing the burn token action in the blockchain.**

#### Request Body

| Name                | Type   | Description                                       |
| ------------------- | ------ | ------------------------------------------------- |
| blockchainAddress   | string | Address where the money will be withdrawn         |
| currency            | string | Currency of the funds to withdraw                 |
| identityId          | string | Id of the identity associated to the request      |
| transferInformation | object | Object containing the information of the transfer |

{% tabs %}
{% tab title="200 " %}

```
{
    "id": "2642dedd-4fa0-40bf-8b15-7c0513bcdb38",
    "identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
    "transactionReference": "0xf6cce2d20d2714fa7be8e1bb8b8cf0abbb12ca3d34d000073742a4da954c1be5",
    "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
    "amount": null,
    "currency": "USD",
    "transactionHash": null,
    "transferInformation": {
        "transferType": "wire",
		    "bankAccountName": "Jonh do bank",
		    "bankAccountNumber": "1321312312321312",
		    "routingNumber": "123456789"
    },
    "status": "prepared",
    "paymentDetails": null,
    "transactionNumber": null,
    "specialType": null,
    "createdAt": "2020-02-19T11:43:04.553Z",
    "updatedAt": "2020-02-19T11:43:04.553Z"
}
```

{% endtab %}

{% tab title="403 Response given when the identity is not yet approved." %}

```
{
    "code": "identity_not_approved",
    "status": 403
}
```

{% endtab %}
{% endtabs %}

#### **Example Call**

{% tabs %}
{% tab title="Request" %}

```javascript
POST [ENVIRONMENT HOSTNAME]/withdrawals

{
	"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
	"currency": "USD",
	"identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
	"transferInformation": {
		"transferType": "wire",
		"bankAccountName": "Jonh do bank",
		"bankAccountNumber": "1321312312321312",
		"routingNumber": "123456789"
	}
}
```

{% endtab %}

{% tab title="Curl" %}

```
curl -X POST \
  [ENVIRONMENT HOSTNAME]/withdrawals \
  -H 'Content-Type: application/json' \
  -H 'apikey: {INSERT API KEY HERE}' \
  -d '{
    "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
    "currency": "USD",
    "identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
    "transferInformation": {
	     "transferType": "wire",
		   "bankAccountName": "Jonh do bank",
		   "bankAccountNumber": "1321312312321312",
		   "routingNumber": "123456789"
	  }
}'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "2642dedd-4fa0-40bf-8b15-7c0513bcdb38",
    "identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
    "transactionReference": "0xf6cce2d20d2714fa7be8e1bb8b8cf0abbb12ca3d34d000073742a4da954c1be5",
    "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
    "amount": null,
    "currency": "USD",
    "transactionHash": null,
    "transferInformation": {
        "transferType": "wire",
		    "bankAccountName": "Jonh do bank",
		    "bankAccountNumber": "1321312312321312",
		    "routingNumber": "123456789"
    },
    "status": "prepared",
    "createdAt": "2020-02-19T11:43:04.553Z",
    "updatedAt": "2020-02-19T11:43:04.553Z"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
On the **Sandbox** environment, you can use the [settle withdrawal ](/api/sandbox#settle-withdrawal)endpoint to simulate and settle the withdrawal request you created.
{% endhint %}

## POST /withdrawals/:id/submit

<mark style="color:green;">`POST`</mark> `[ENVIRONMENT HOSTNAME]/withdrawals/:id/submit`

This method can be used to submit a withdrawal **after the tokens were burned in the blockchain.** This endpoint receives the **transactionHash** of the burn operation has a body parameter. This will be used to check if the transaction operation matches the data provided when creating the withdrawal request.\ <br>

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | Withdrawal id to be submitted |

#### Request Body

| Name            | Type   | Description                            |
| --------------- | ------ | -------------------------------------- |
| transactionHash | string | Transaction hash of the burn operation |

{% tabs %}
{% tab title="200 " %}

```
{
    "id": "37e2b53c-f938-4dce-90ef-7614f7e338f5",
    "identityId": "80d82e03-527e-46ff-b5a2-6e5d7d34115c",
    "transferType": "wire",
    "transactionReference": "0x8722597478bb2ab2964576b9509941269642c2d960ac7bc452cd8cd5f9e64f2e",
    "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
    "amount": "10",
    "currency": "USD",
    "transactionHash": "0xfa7102053dceb6cdc59b1580706a9fec7b14333d30d041ad4f03b0d8359f63c8",
    "transferMethodId": null,
    "status": "submitted",
    "paymentDetails": null,
    "transactionNumber": null,
    "specialType": null,
    "createdAt": "2020-02-19T17:20:35.948Z",
    "updatedAt": "2020-02-19T17:23:21.068Z"
}
```

{% endtab %}
{% endtabs %}

#### **Example Call**

{% tabs %}
{% tab title="Request" %}

```javascript
POST [ENVIRONMENT HOSTNAME]/withdrawals/37e2b53c-f938-4dce-90ef-7614f7e338f5/submit
```

{% endtab %}

{% tab title="Curl" %}

```
curl --location --request POST 'localhost:3000/withdrawals/37e2b53c-f938-4dce-90ef-7614f7e338f5/submit' \
--header 'Content-Type: application/json' \
--header 'apikey: {{INSERT YOUR API KEY HERE}}' \
--data-raw '{
	"transactionHash": "0xfa7102053dceb6cdc59b1580706a9fec7b14333d30d041ad4f03b0d8359f63c8"
}'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "37e2b53c-f938-4dce-90ef-7614f7e338f5",
    "identityId": "80d82e03-527e-46ff-b5a2-6e5d7d34115c",
    "transferType": "wire",
    "transactionReference": "0x8722597478bb2ab2964576b9509941269642c2d960ac7bc452cd8cd5f9e64f2e",
    "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
    "amount": "10",
    "currency": "USD",
    "transactionHash": "0xfa7102053dceb6cdc59b1580706a9fec7b14333d30d041ad4f03b0d8359f63c8",
    "transferMethodId": null,
    "status": "submitted",
    "createdAt": "2020-02-19T17:20:35.948Z",
    "updatedAt": "2020-02-19T17:23:21.068Z"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
On the **Sandbox** environment, you can use the [settle withdrawal ](/api/sandbox#settle-withdrawal)endpoint to simulate and settle the withdrawal request you created.
{% endhint %}

## GET /withdrawals/:id

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]/withdrawals/:id`

This endpoint retrieves a single `withdrawal` that you've created by its specific `id` attribute.

#### Path Parameters

| Name | Type   | Description                        |
| ---- | ------ | ---------------------------------- |
| id   | string | Id of the withdrawal to be fetched |

{% tabs %}
{% tab title="200 " %}

```
{
    "id": "6f0c5931-326d-431a-87b8-5368dcdf6d61",
    "identityId": "28961623-68b4-4fe3-bb16-9636eac5aab2",
    "transferInformation": {
        "transferType": "wire",
        "bankAccountName": "Jonh do bank",
		    "bankAccountNumber": "1321312312321312",
		    "routingNumber": "123456789"
    },
    "transactionReference": "0xd570c59208bd0cd8b5f29d7df86015aa31e0c978e38b6695cf309e0bd77e2764",
    "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
    "amount": null,
    "currency": "USD",
    "transactionHash": null,
    "status": "prepared",
    "paymentDetails": null,
    "transactionNumber": null,
    "specialType": null,
    "createdAt": "2020-02-18T14:41:01.757Z",
    "updatedAt": "2020-02-18T14:41:01.757Z"
}
```

{% endtab %}
{% endtabs %}

####

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/withdrawals/6f0c5931-326d-431a-87b8-5368dcdf6d61
```

{% endtab %}

{% tab title="Curl" %}

```
curl -X GET \
  [ENVIRONMENT HOSTNAME]/withdrawals/6f0c5931-326d-431a-87b8-5368dcdf6d61 \
  -H 'apikey: {INSERT API KEY HERE}'
  
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "6f0c5931-326d-431a-87b8-5368dcdf6d61",
    "identityId": "28961623-68b4-4fe3-bb16-9636eac5aab2",
    "transferInformation": {
        "transferType": "wire",
        "bankAccountName": "Jonh do bank",
		    "bankAccountNumber": "1321312312321312",
		    "routingNumber": "123456789"
    },
    "transactionReference": "0xd570c59208bd0cd8b5f29d7df86015aa31e0c978e38b6695cf309e0bd77e2764",
    "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
    "amount": null,
    "currency": "USD",
    "transactionHash": null,
    "status": "prepared",
    "createdAt": "2020-02-18T14:41:01.757Z",
    "updatedAt": "2020-02-18T14:41:01.757Z"
}
```

{% endtab %}
{% endtabs %}

## GET /withdrawals

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]/withdrawals/`

This endpoint returns a list of all `withdrawals` submitted by you.\
*This endpoint supports pagination.*

{% tabs %}
{% tab title="200 " %}

```
{
    "total": 1,
    "data": [
        {
            "id": "6f0c5931-326d-431a-87b8-5368dcdf6d61",
            "identityId": "28961623-68b4-4fe3-bb16-9636eac5aab2",
            "transferInformation": {
                "transferType": "wire",
                "bankAccountName": "Jonh do bank",
		            "bankAccountNumber": "1321312312321312",
		            "routingNumber": "123456789"
            },
            "transactionReference": "0xd570c59208bd0cd8b5f29d7df86015aa31e0c978e38b6695cf309e0bd77e2764",
            "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
            "amount": null,
            "currency": "USD",
            "transactionHash": null,
            "status": "prepared",
            "createdAt": "2020-02-18T14:41:01.757Z",
            "updatedAt": "2020-02-18T14:41:01.757Z"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

####

#### Example call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/withdrawals

// PAGINATED

GET [ENVIRONMENT HOSTNAME]/withdrawals?page[number]=1&page[size]=1
```

{% endtab %}

{% tab title="Curl" %}

```
curl -X GET \
  [ENVIRONMENT HOSTNAME]/withdrawals \
  -H 'apikey: {INSERT API KEY HERE}'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "total": 1,
    "data": [
        {
            "id": "6f0c5931-326d-431a-87b8-5368dcdf6d61",
            "identityId": "28961623-68b4-4fe3-bb16-9636eac5aab2",
            "transferInformation": {
                "transferType": "wire",
                "bankAccountName": "Jonh do bank",
		            "bankAccountNumber": "1321312312321312",
		            "routingNumber": "123456789"
            },
            "transactionReference": "0xd570c59208bd0cd8b5f29d7df86015aa31e0c978e38b6695cf309e0bd77e2764",
            "blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
            "amount": null,
            "currency": "USD",
            "transactionHash": null,
            "status": "prepared",
            "createdAt": "2020-02-18T14:41:01.757Z",
            "updatedAt": "2020-02-18T14:41:01.757Z"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


# Verifications

The following endpoints are used to insert and retrieve entries representing `verifications` (of an identity's documents) from the database.

{% tabs %}
{% tab title="VERIFICATIONS ENDPOINTS" %}

```
GET /verifications/:id
GET /verifications
```

{% endtab %}
{% endtabs %}

## The `verification` object

The `verification` object represents the result of a `document`'s check by a KYC partner.&#x20;

A `verification` is identified by a unique, random `id` and relates to a user's `identityId`.&#x20;

{% tabs %}
{% tab title="VERIFICATIONS OBJECT" %}

```javascript
{
    "id": "3519322a-6881-472f-8e1f-2486d5f3cb15",
    "identityId": "e0564926-96e0-42e2-a544-68bc18598e40",
    "status": "pending",
    "exceptionDetails": "",
    "createdAt": "2020-01-09T10:21:05.760Z",
    "updatedAt": "2020-01-15T13:12:21.860Z"
}
```

{% endtab %}
{% endtabs %}

## GET /verifications/:id

<mark style="color:blue;">`GET`</mark> `https://api.publicmint.com/verifications/:id`

This endpoint retrieves a specific verification by its unique `id` attribute.

#### Path Parameters

| Name | Type   | Description            |
| ---- | ------ | ---------------------- |
| id   | string | Id of the verification |

{% tabs %}
{% tab title="200 " %}

```
{
    "id": "1c1b39a2-f8ec-4680-82cd-09926e1a2c95",
    "identity_id": "7d0e05c3-73b3-45a7-af03-0ec7e89c9dd7",
    "status": "pending",
    "exception_details": "",
    "external_id": "5b161fd6-66a3-4a44-9e1e-738d2b5a573f",
    "external_system": "PrimeTrust",
    "integ_status": "waiting",
    "integ_messages": null,
    "created_at": "2019-11-11T17:47:13.221Z",
    "updated_at": "2019-11-11T17:50:14.83
```

{% endtab %}
{% endtabs %}

#### Request

{% tabs %}
{% tab title="Request" %}

```javascript
GET https://api.sandbox.publicmint.io/verifications/ddec6616-b29f-4517-98f9-612ec7859120
```

{% endtab %}

{% tab title="Curl" %}

```
curl -X GET \
  https://api.sandbox.publicmint.io/verifications/1c1b39a2-f8ec-4680-82cd-09926e1a2c95 \
  -H 'apikey: {INSERT API KEY HERE}'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "3519322a-6881-472f-8e1f-2486d5f3cb15",
    "identityId": "e0564926-96e0-42e2-a544-68bc18598e40",
    "status": "pending",
    "exceptionDetails": "",
    "createdAt": "2020-01-09T10:21:05.760Z",
    "updatedAt": "2020-01-15T13:12:21.860Z"
}
```

{% endtab %}
{% endtabs %}

## GET /verifications

<mark style="color:blue;">`GET`</mark> `https://api.publicmint.com/verifications`

This endpoint returns a list of all `verifications` associated with you. *This endpoint supports pagination.*

{% tabs %}
{% tab title="200 " %}

```
{
    "total": 32,
    "data": [
        {
            "id": "3519322a-6881-472f-8e1f-2486d5f3cb15",
            "identityId": "e0564926-96e0-42e2-a544-68bc18598e40",
            "status": "pending",
            "exceptionDetails": "",
            "createdAt": "2020-01-09T10:21:05.760Z",
            "updatedAt": "2020-01-15T13:12:21.860Z"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET https://api.sandbox.publicmint.io/verifications

// Paginated

GET https://api.sandbox.publicmint.io/verifications?page[number]=1&page[size]=1
```

{% endtab %}

{% tab title="Curl" %}

```
curl -X GET \
  'https://api.sandbox.publicmint.io/verifications?page[number]=1&page[size]=1' \
  -H 'apikey: {INSERT API KEY HERE}'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "total": 32,
    "data": [
        {
            "id": "3519322a-6881-472f-8e1f-2486d5f3cb15",
            "identityId": "e0564926-96e0-42e2-a544-68bc18598e40",
            "status": "pending",
            "exceptionDetails": "",
            "createdAt": "2020-01-09T10:21:05.760Z",
            "updatedAt": "2020-01-15T13:12:21.860Z"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


# Identity Relations

The following endpoints are used to insert, retrieve, or delete entries representing identity relations from the database.&#x20;

{% tabs %}
{% tab title="IDENTITY RELATIONS ENDPOINTS" %}

```
GET /identity-relations/:id
POST /identity-relations/
DELETE /identity-relations/:id
```

{% endtab %}
{% endtabs %}

## The `identity-relation` object

The `identity-relation` object establishes the relation between a **company identity** and a person/company that is also a **company officer.**

A given `identity-relation` is identified by a unique, random `id` parameter.

{% tabs %}
{% tab title="IDENTITY RELATION OBJECT" %}

```javascript
{
    "id": "8b5e19fd-424f-4187-bb5f-a33a54bb38fa",
    "fromIdentity": "6030f456-bcf7-4309-8de2-5ef2871c07d0",
    "toIdentity": "a5b1857d-919f-4faa-859c-be665e5a6d9f",
    "label": "CEO",
    "createdAt": "2020-02-19T15:47:39.993Z",
    "updatedAt": "2020-02-19T15:47:39.993Z"
}
```

{% endtab %}
{% endtabs %}

## GET /identity-relations/:id

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]/identity-relations/:id`

This endpoint allows to retrieve a specific identity relation.

#### Path Parameters

| Name | Type   | Description                 |
| ---- | ------ | --------------------------- |
| id   | string | Id of the identity relation |

{% tabs %}
{% tab title="200 " %}

```
{
    "id": "8b5e19fd-424f-4187-bb5f-a33a54bb38fa",
    "fromIdentity": "6030f456-bcf7-4309-8de2-5ef2871c07d0",
    "toIdentity": "a5b1857d-919f-4faa-859c-be665e5a6d9f",
    "label": "CEO",
    "createdAt": "2020-02-19T15:47:39.993Z",
    "updatedAt": "2020-02-19T15:47:40.944Z"
}
```

{% endtab %}
{% endtabs %}

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/identity-relations/8b5e19fd-424f-4187-bb5f-a33a54bb38fa

```

{% endtab %}

{% tab title="Curl" %}

```
curl -X POST \
  [ENVIRONMENT HOSTNAME]/identity-relations/8b5e19fd-424f-4187-bb5f-a33a54bb38fa \
  -H 'Content-Type: application/json' \
  -H 'apikey: {INSERT YOUR API KEY HERE}' \
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "8b5e19fd-424f-4187-bb5f-a33a54bb38fa",
    "fromIdentity": "6030f456-bcf7-4309-8de2-5ef2871c07d0",
    "toIdentity": "a5b1857d-919f-4faa-859c-be665e5a6d9f",
    "label": "CEO",
    "createdAt": "2020-02-19T15:47:39.993Z",
    "updatedAt": "2020-02-19T15:47:39.993Z"
}
```

{% endtab %}
{% endtabs %}

## POST /identity-relations

<mark style="color:green;">`POST`</mark> `[ENVIRONMENT HOSTNAME]/identity-relations/`

This endpoint allows you to submit a new identity relation between two `identities` on the database. One of the `identities` must belong to an individual company officer, with the other belonging to the company in question.

#### Request Body

| Name              | Type   | Description                                                |
| ----------------- | ------ | ---------------------------------------------------------- |
| relations         | array  | Array of objects containing the relations information      |
| companyIdentityId | string | Id of the company to whom will be associated the relations |

{% tabs %}
{% tab title="200 Deposit successfully inserted in the database." %}

```javascript
{
    "id": "8b5e19fd-424f-4187-bb5f-a33a54bb38fa",
    "fromIdentity": "6030f456-bcf7-4309-8de2-5ef2871c07d0",
    "toIdentity": "a5b1857d-919f-4faa-859c-be665e5a6d9f",
    "label": "CEO",
    "createdAt": "2020-02-19T15:47:39.993Z",
    "updatedAt": "2020-02-19T15:47:39.993Z"
}
```

{% endtab %}
{% endtabs %}

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
POST [ENVIRONMENT HOSTNAME]/identity-relations/

```

{% endtab %}

{% tab title="Curl" %}

```
curl -X POST \
  [ENVIRONMENT HOSTNAME]/identity-relations \
  -H 'Content-Type: application/json' \
  -H 'apikey: {INSERT YOUR API KEY HERE}' \
  -d '{
  "companyIdentityId": "f51c7041-fdab-4f03-acaf-9c34df178724",
	"relations": [
		{
			"id": "f51c7041-fdab-4f03-acaf-9c34df178724",
			"label": "CEO"
		}
	] 
}
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "8b5e19fd-424f-4187-bb5f-a33a54bb38fa",
    "fromIdentity": "6030f456-bcf7-4309-8de2-5ef2871c07d0",
    "toIdentity": "a5b1857d-919f-4faa-859c-be665e5a6d9f",
    "label": "CEO",
    "createdAt": "2020-02-19T15:47:39.993Z",
    "updatedAt": "2020-02-19T15:47:39.993Z"
}
```

{% endtab %}
{% endtabs %}

## DELETE /identity-relations/:id

<mark style="color:red;">`DELETE`</mark> `[ENVIRONMENT HOSTNAME]/identity-relations/:id`

This endpoint is used to delete a specific `identity-relation`.

#### Path Parameters

| Name | Type   | Description                               |
| ---- | ------ | ----------------------------------------- |
| id   | string | Id of the identity relation to be deleted |

{% tabs %}
{% tab title="200 " %}

```





```

{% endtab %}
{% endtabs %}

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
DELETE [ENVIRONMENT HOSTNAME]/identity-relations/edd56760-39e7-45cd-8ca6-21add09ac548

```

{% endtab %}

{% tab title="Curl" %}

```
curl -X DELETE \
  [ENVIRONMENT HOSTNAME]/identity-relations/edd56760-39e7-45cd-8ca6-21add09ac548 \
  -H 'apikey: {INSERT API KEY HERE}'
```

{% endtab %}
{% endtabs %}


# Documents

This resource corresponds to a digitized document hosted on Public Mint's servers in `file` format.

{% tabs %}
{% tab title="ENDPOINTS" %}

```
POST /documents
GET /documents/:id
GET /documents
DELETE /documents/:id
```

{% endtab %}
{% endtabs %}

## The `document` object

The `document` object represents a digitized document (generally a government ID or proof of address) in the shape of a file uploaded to Public Mint's servers.

A `document` is identified by a unique, random `id` and relates to a user's `identityId`.&#x20;

{% tabs %}
{% tab title="DOCUMENT OBJECT" %}

```javascript
{
    "id": "e9cbc096-bb79-438b-93ac-7c15dfdb1274",
    "identityId": "971c3241-9876-471e-b0b3-40040893efd0",
    "status": "pending",
    "label": "identity card",
    "description": "identity card of jonh smith",
    "extension": ".png",
    "fileUrl": "https://pmint-custodial-api-tst-identity-docs.s3.amazonaws.com/97/1c/32/41/LaDRHrVEScopeYBT.png",
    "documentType": "IdentityCard",
    "documentSide": "FrontSide",
    "createdAt": "2021-02-17T14:03:51.974Z",
    "updatedAt": "2021-02-17T14:03:51.974Z",
    "deletedAt": null
}
```

{% endtab %}
{% endtabs %}

## POST /documents

<mark style="color:green;">`POST`</mark> `[ENVIRONMENT HOSTNAME]/documents`

This endpoint allows you to submit a new document to the database. If all parameters are valid, a new record will be added to the database.

#### Request Body

| Name         | Type   | Description                                                                                                                                                                                                                                                                                             |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| description  | string | Description associated to the document                                                                                                                                                                                                                                                                  |
| documentSide | string | <p>Side of the document<br><br><strong>Must be one of the following:</strong><br> <strong>- FrontSide</strong><br> <strong>- BackSide</strong></p>                                                                                                                                                      |
| documentType | string | <p>Type of the document<br><br><strong>Must be one of the following:</strong><br> <strong>- IdentityCard;</strong><br> <strong>- DriverLicense;</strong><br> <strong>- Passport;</strong><br> <strong>- ResidencePermit;</strong><br> <strong>- UtilityBill;</strong><br> <strong>- Other.</strong></p> |
| identityId   | string | Id of the identity associated to the document.                                                                                                                                                                                                                                                          |
| label        | string | Label for the document.                                                                                                                                                                                                                                                                                 |
| file         | object | <p>Document file<br><br><strong>Requirements:</strong><br> <strong>- Needs to be a file;</strong><br> <strong>- Needs to be the last field in the       form</strong></p>                                                                                                                               |

{% tabs %}
{% tab title="200 Deposit successfully inserted in the database." %}

```javascript
{
    "id": "e9cbc096-bb79-438b-93ac-7c15dfdb1274",
    "identityId": "971c3241-9876-471e-b0b3-40040893efd0",
    "status": "pending",
    "label": "identity card",
    "description": "identity card of jonh smith",
    "extension": ".png",
    "fileUrl": "https://pmint-custodial-api-tst-identity-docs.s3.amazonaws.com/97/1c/32/41/LaDRHrVEScopeYBT.png",
    "documentType": "IdentityCard",
    "documentSide": "FrontSide",
    "createdAt": "2021-02-17T14:03:51.974Z",
    "updatedAt": "2021-02-17T14:03:51.974Z",
    "deletedAt": null
}
```

{% endtab %}
{% endtabs %}

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
POST [ENVIRONMENT HOSTNAME]/documents


```

{% endtab %}

{% tab title="Curl" %}

```
curl --location --request POST 'https://api.tst.publicmint.io/documents' \
--header 'apiKey: J8fMImECtv0jAYXJ8D6gS48z45B3YeC5' \
--form 'description="identity card of jonh smith"' \
--form 'label="identity card"' \
--form 'identityId="971c3241-9876-471e-b0b3-40040893efd0"' \
--form 'documentType="IdentityCard"' \
--form 'documentSide="FrontSide"' \
--form 'file=@"/Users/foo/Screen Shot 2021-02-04 at 14.33.01.png"'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "e9cbc096-bb79-438b-93ac-7c15dfdb1274",
    "identityId": "971c3241-9876-471e-b0b3-40040893efd0",
    "status": "pending",
    "label": "identity card",
    "description": "identity card of jonh smith",
    "extension": ".png",
    "fileUrl": "https://pmint-custodial-api-tst-identity-docs.s3.amazonaws.com/97/1c/32/41/LaDRHrVEScopeYBT.png",
    "documentType": "IdentityCard",
    "documentSide": "FrontSide",
    "createdAt": "2021-02-17T14:03:51.974Z",
    "updatedAt": "2021-02-17T14:03:51.974Z",
    "deletedAt": null
}
```

{% endtab %}
{% endtabs %}

## GET /documents/:id

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]/documents/:id`

This endpoint retrieves a single document that you own by its specific `id` attribute.

#### Path Parameters

| Name | Type   | Description                        |
| ---- | ------ | ---------------------------------- |
| id   | string | Id of the document to be retrieved |

{% tabs %}
{% tab title="200 " %}

```
{
    "id": "0acb6a86-e21e-45d6-a4e5-70bd4f85ecae",
    "identityId": "e0564926-96e0-42e2-a544-68bc18598e40",
    "status": "active",
    "label": "identity card",
    "description": "identity card of jonh smith",
    "extension": ".jpeg",
    "fileUrl": "https://pmint-custodial-api-tst-identity-docs.s3.amazonaws.com/e0/56/49/26/N5MXjSIhK0bGAOt2.jpeg",
    "documentType": "IdentityCard",
    "documentSide": "FrontSide",
    "createdAt": "2020-01-10T17:24:23.561Z",
    "updatedAt": "2020-01-10T17:24:24.455Z",
    "deletedAt": null
}
```

{% endtab %}
{% endtabs %}

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/documents/0acb6a86-e21e-45d6-a4e5-70bd4f85ecae

```

{% endtab %}

{% tab title="Curl" %}

```
curl -X GET \
  [ENVIRONMENT HOSTNAME]/documents/0acb6a86-e21e-45d6-a4e5-70bd4f85ecae \
  -H "apikey: {INSERT YOUR API KEY HERE}" \
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "0acb6a86-e21e-45d6-a4e5-70bd4f85ecae",
    "identityId": "e0564926-96e0-42e2-a544-68bc18598e40",
    "status": "active",
    "label": "identity card",
    "description": "identity card of jonh smith",
    "extension": ".jpeg",
    "fileUrl": "https://pmint-custodial-api-tst-identity-docs.s3.amazonaws.com/e0/56/49/26/N5MXjSIhK0bGAOt2.jpeg",
    "documentType": "IdentityCard",
    "documentSide": "FrontSide",
    "createdAt": "2020-01-10T17:24:23.561Z",
    "updatedAt": "2020-01-10T17:24:24.455Z",
    "deletedAt": null
}
```

{% endtab %}
{% endtabs %}

## GET /documents

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]/documents`

This endpoint returns a list of all documents submitted by you.

{% tabs %}
{% tab title="200 " %}

```
{
    "total": 1,
    "data": [
        {
            "id": "0acb6a86-e21e-45d6-a4e5-70bd4f85ecae",
            "identityId": "e0564926-96e0-42e2-a544-68bc18598e40",
            "status": "active",
            "label": "identity card",
            "description": "identity card of jonh smith",
            "extension": ".jpeg",
            "fileUrl": "https://pmint-custodial-api-tst-identity-docs.s3.amazonaws.com/e0/56/49/26/N5MXjSIhK0bGAOt2.jpeg",
            "documentType": "IdentityCard",
            "documentSide": "FrontSide",
            "createdAt": "2020-01-10T17:24:23.561Z",
            "updatedAt": "2020-01-10T17:24:24.455Z",
            "deletedAt": null
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/documents
  
// PAGINATED

GET [ENVIRONMENT HOSTNAME]/documents?page[number]=1&page[size]=1
```

{% endtab %}

{% tab title="Curl" %}

```
curl -X GET \
  "[ENVIRONMENT HOSTNAME]/documents" \
  -H "apikey: {INSERT YOUR API KEY HERE}" \
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "total": 1,
    "data": [
        {
             "id": "0acb6a86-e21e-45d6-a4e5-70bd4f85ecae",
            "identityId": "e0564926-96e0-42e2-a544-68bc18598e40",
            "status": "active",
            "label": "identity card",
            "description": "identity card of jonh smith",
            "extension": ".jpeg",
            "fileUrl": "https://pmint-custodial-api-tst-identity-docs.s3.amazonaws.com/e0/56/49/26/N5MXjSIhK0bGAOt2.jpeg",
            "documentType": "IdentityCard",
            "documentSide": "FrontSide",
            "createdAt": "2020-01-10T17:24:23.561Z",
            "updatedAt": "2020-01-10T17:24:24.455Z",
            "deletedAt": null
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## DELETE /documents/:id

<mark style="color:red;">`DELETE`</mark> `[ENVIRONMENT HOSTNAME]/documents/:id`

Deletes a specific document by it's id.

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Document id |

{% tabs %}
{% tab title="204 " %}

```
```

{% endtab %}
{% endtabs %}


# Deposits (deprecated)

{% hint style="danger" %}
These endpoints are deprecated and will be discontinued by November 1st. Please make sure you migrate your implementation to the new [deposits flow](/api/funding/deposit-wire).
{% endhint %}

To initiate a deposit, create a `deposit` object via the `/deposits` endpoint. If you want to create an **ACH** type deposit, you need to have created at least one [transfer method](broken://pages/-Lruqvllr_O_Je0mkbPY) in order to make a deposit.

{% tabs %}
{% tab title="ENDPOINTS" %}

```
POST /deposits
GET /deposits/:id
GET /deposits
```

{% endtab %}
{% endtabs %}

## The `deposit` object

The `deposit` object represents a request for depositing fiat into the blockchain. You can create or retrieve an `identityId`'s deposits via request to the API. Or, if you manage multiple identities in the network, you can also retrieve a list of deposits for all of them.

Deposits are identified by a unique, random `id`, and relate to a user's `identityId`

{% tabs %}
{% tab title="DEPOSITS OBJECT" %}

```javascript
{
    "id": "3305af3a-e3c8-4f73-a46b-58c0d6376825",
    "identityId": "971c3241-9876-471e-b0b3-40040893efd0",
    "amount": "12",
    "currency": "USD",
    "blockchainAddress": "0x359f194ce353b1415abff5fcb07baf59f0bda0de",
    "transferMethodInformation": {
        "transferType": "wire"
    },
    "status": "pending",
    "reference": null,
    "createdAt": "2021-02-17T18:02:50.365Z",
    "updatedAt": "2021-02-17T18:02:50.365Z"
}
```

{% endtab %}
{% endtabs %}

## POST /deposits

<mark style="color:green;">`POST`</mark> `[ENVIRONMENT HOSTNAME]/deposits`

This endpoint allows you to add a new deposit to the database. If all the params are valid, a new record will be inserted in the database with the deposit information.

#### Request Body

| Name                | Type   | Description                                          |
| ------------------- | ------ | ---------------------------------------------------- |
| amount              | string | Amount of the deposit                                |
| currency            | string | Currency associated to the deposit funds             |
| identityId          | string | Id of the identity associated to the deposit         |
| blockchainAddress   | string | Blockchain address to where the funds will be minted |
| transferInformation | object | Deposit transfer information                         |

{% tabs %}
{% tab title="200 Deposit successfully inserted in the database." %}

```javascript
{
    "id": "ea5894d2-2657-424a-906e-0f9c345ab48b",
    "identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
    "transferMethodId": null,
    "amount": "11",
    "currency": "USD",
    "blockchainAddress": "0xF2A511240E0D6b7E9683Ff979b4C4Afb9d3fE2E9",
    "message": null,
    "status": "waiting",
    "fundsTransferDetails": null,
    "reference": null,
    "transferType": "wire",
    "createdAt": "2020-02-19T11:15:08.144Z",
    "updatedAt": "2020-02-19T11:15:08.144Z"
}
```

{% endtab %}

{% tab title="400 Response given when any of the parameters is invalid." %}

```
{
  "code": "invalid_data_format",
  "status": "400"
}
```

{% endtab %}

{% tab title="500 Error when calling the API." %}

```
{
  "code": "internal_server_error",
  "status": "500"

```

{% endtab %}
{% endtabs %}

**Note: The** `transferInformation` **object needs specific information depending on the kind of deposit you intend to create. In the example bellow, you can find the information necessary to create all the deposit types.**

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
POST [ENVIRONMENT HOSTNAME]/deposits

// BODY for Wire deposits

{
	"amount": "11",
	"currency": "USD",
	"identityId": "{{identityId}}",
	"blockchainAddress": "{{identityId}}",
	"transferInformation": {
		"transferType": "wire"
	}
}

// BODY for International Wire deposits

{
	"amount": "11",
	"currency": "USD",
	"identityId": "{{identityId}}",
	"blockchainAddress": "{{blockchainAddress}}",
	"transferInformation": {
		"transferType": "internationalWire"
	}
}

// BODY for USDC deposits

{
	"amount": "11",
	"currency": "USD",
	"identityId": "{{identityId}}",
	"blockchainAddress": "{{blockchainAddress}}",
	"transferInformation": {
		"transferType": "scUsdc"
	}
}
```

{% endtab %}

{% tab title="Curl" %}

```
curl -X POST \
  [ENVIRONMENT HOSTNAME]/deposits \
  -H 'Content-Type: application/json' \
  -H 'apikey: {INSERT API KEY HERE}' \
  -d '{
	"amount": "12",
	"currency": "USD",
	"identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
	"blockchainAddress": "0xA4597E696a55fD76430945e0940DA17c72337ccC",
	"transferInformation": {
		"transferType": "wire"
	}
}'
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "3305af3a-e3c8-4f73-a46b-58c0d6376825",
    "identityId": "971c3241-9876-471e-b0b3-40040893efd0",
    "amount": "12",
    "currency": "USD",
    "blockchainAddress": "0x359f194ce353b1415abff5fcb07baf59f0bda0de",
    "transferMethodInformation": {
        "transferType": "wire"
    },
    "status": "waiting",
    "reference": null,
    "createdAt": "2021-02-17T18:02:50.365Z",
    "updatedAt": "2021-02-17T18:02:50.365Z"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
On the **Sandbox** environment, you can use the [settle deposit ](/api/sandbox#settle-deposit)endpoint to simulate and settle the deposit request you created.
{% endhint %}

On the **Sandbox** environment, you can use the [approve KYC ](/api/sandbox#approve-kyc)endpoint to simulate and approve the identity you created.

## GET /deposits/:id

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]/deposits/:id`

This endpoint retrieves a single deposit that you've created by its specific `id` attribute.

{% tabs %}
{% tab title="200 " %}

```
{
    "id": "ee1ce972-0dfc-45fc-98bf-0fc90a7f86db",
    "identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
    "amount": "12",
    "currency": "USD",
    "blockchainAddress": "0x6257EaCbB030ed1B33d11Aa841B2511B1B444937",
    "message": null,
    "status": "pending",
    "fundsTransferDetails": null,
    "reference": null,
    "transferInformation": {
		    "transferType": "wire"
	  },
    "createdAt": "2020-02-19T11:17:20.567Z",
    "updatedAt": "2020-02-19T11:17:21.241Z"
}
```

{% endtab %}
{% endtabs %}

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/deposits/b22d80d9-0e14-4e4f-8101-881dd7138bc5
```

{% endtab %}

{% tab title="Curl" %}

```
curl -X GET \
  [ENVIRONMENT HOSTNAME]/deposits/7b6bbb41-b0e0-4058-b59e-ea3181f854ec \
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "id": "3305af3a-e3c8-4f73-a46b-58c0d6376825",
    "identityId": "971c3241-9876-471e-b0b3-40040893efd0",
    "amount": "12",
    "currency": "USD",
    "blockchainAddress": "0x359f194ce353b1415abff5fcb07baf59f0bda0de",
    "transferMethodInformation": {
        "transferType": "wire"
    },
    "status": "waiting",
    "reference": null,
    "createdAt": "2021-02-17T18:02:50.365Z",
    "updatedAt": "2021-02-17T18:02:50.365Z"
}
```

{% endtab %}
{% endtabs %}

## GET /deposits

<mark style="color:blue;">`GET`</mark> `[ENVIRONMENT HOSTNAME]/deposits`

This endpoint returns a list of all your deposits.

{% tabs %}
{% tab title="200 " %}

```
{
    "total": 1,
    "data": [
        {
            "id": "a1132d6d-adfc-4ba9-b1ca-e82eaac8199d",
            "identityId": "e0564926-96e0-42e2-a544-68bc18598e40",
            "amount": "12.12",
            "currency": "USD",
            "blockchainAddress": "0x6257EaCbB030ed1B33d11Aa841B2511B1B444937",
            "message": null,
            "status": "waiting",
            "fundsTransferDetails": null,
            "reference": null,
            "transferInformation": {
                "transferType": "wire"
            },
            "createdAt": "2020-01-24T18:02:22.870Z",
            "updatedAt": "2020-01-24T18:02:22.870Z"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
GET [ENVIRONMENT HOSTNAME]/deposits

// PAGINATED

GET [ENVIRONMENT HOSTNAME]/deposits?page[number]=1&page[size]=1
```

{% endtab %}

{% tab title="Curl" %}

```
curl -X GET \
  [ENVIRONMENT HOSTNAME]/deposits/7b6bbb41-b0e0-4058-b59e-ea3181f854ec \
  -H 'apikey: {INSERT API KEY HERE}'
  
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "total": 1,
    "data": [
      {
        "id": "3305af3a-e3c8-4f73-a46b-58c0d6376825",
        "identityId": "971c3241-9876-471e-b0b3-40040893efd0",
        "amount": "12",
        "currency": "USD",
        "blockchainAddress": "0x359f194ce353b1415abff5fcb07baf59f0bda0de",
        "transferMethodInformation": {
            "transferType": "wire"
        },
        "status": "waiting",
        "reference": null,
        "createdAt": "2021-02-17T18:02:50.365Z",
        "updatedAt": "2021-02-17T18:02:50.365Z"
    }]
}
```

{% endtab %}
{% endtabs %}


# Authentication

Authenticate your connection to access API resources

Public Mint uses an [API gateway](https://en.wikipedia.org/wiki/API_management) to authorize, authenticate and route requests to endpoints. All requests require an [API key](/api/reference/authentication#authorization) for authorization and authentication in the request header associated to the key **apikey**, like the example below demonstrates. The key serves to identify the app/partner behind the requests, and which resources they're permitted to access.

**If you don't include your key, or use an invalid one, the request will return an error.**&#x20;

{% tabs %}
{% tab title="Sandbox" %}
{% code title="AUTHENTICATED REQUEST" %}

```bash
$ curl https://api.sandbox.publicmint.io/identities/:id \
  -H "apikey:{YOUR_API_KEY}"
```

{% endcode %}
{% endtab %}

{% tab title="Production" %}
{% code title="AUTHENTICATED REQUEST" %}

```bash
$ curl https://api.publicmint.io/identities/:id \
  -H "apikey:{YOUR_API_KEY}"
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Authorization and authentication

Authorization to our public APIs requires a partner API key. To be eligible, you need to be a verified business partner. You can learn more about how to apply at the [Partners section](broken://pages/-LnCk0-aqUbrHKUzaVJN).

When your application is successful you'll receive a confirmation email giving you access to the Partners Portal (coming soon), where you'll be able to generate, revoke and manage your API keys.&#x20;

{% hint style="success" %}
While we work on finalizing the Partner's Portal, please contact us directly to request early access to our API.
{% endhint %}

You'll need to pass on your API key in the request headers when making calls to Public Mint's endpoints to [authenticate your requests](/api/reference/authentication#Authorization) and identify witch application/partner is using the APIs.

API keys also serve to authenticate user sessions.&#x20;


# Pagination

Some of our endpoints supports pagination. This can be achieved by passing specific params in the request **query** string. As an example, the code bellow showcases how to use this feature when using the [GET /deposits](/api/reference/deposits#get-deposits) endpoint.

#### Example Call

{% tabs %}
{% tab title="Request" %}

```javascript
// PAGINATED

GET [ENVIRONMENT HOSTNAME]/deposits?page[number]=1&page[size]=1
```

{% endtab %}

{% tab title="Response" %}

```
{
    "total": 1,
    "data": [
        {
            "id": "b22d80d9-0e14-4e4f-8101-881dd7138bc5",
            "identity_id": "7c8867d7-b9b8-40de-86c7-f4a8e4ee566d",
            "amount": "12.000000000000",
            "currency": "USD",
            "blockchain_address": "0x6257EaCbB030ed1B33d11Aa841B2511B1B444937",
            "message": null,
            "status": "waiting",
            "funds_transfer_details": null,
            "reference": null,
            "transferInformation": {
        		    "transferType": "wire",
        		    "bankAccountName": "Josh Smith",
        		    "bankAccountNumber": "38231823182318219",
        		    "routingNumber": "312323123"
        	  },
            "web_hook_url": "https://enfp40vp60yhq.x.pipedream.net",
            "external_id": null,
            "external_system": null,
            "integ_status": "waiting",
            "integ_messages": null,
            "created_at": "2019-11-08T12:19:53.219Z",
            "updated_at": "2019-11-08T12:19:53.219Z"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

**The following endpoints supports pagination:**

* [GET /identities](/api/reference/identities#get-identities)
* [GET /identities/:id/deposits](/api/reference/identities#get-identities-id-deposits)
* [GET /identities/:id/withdrawals](/api/reference/identities#get-identities-id-withdrawals)
* [GET /identities/:id/documents](/api/reference/identities#get-identities-id-documents)
* [GET /identities/:id/verifications](/api/reference/identities#get-identities-id-verifications)
* [GET /identities/:id/identity-relations](/api/reference/identities#get-identities-id-identity-relations)
* [GET /documents](/api/reference/documents#get-documents)
* [GET /withdrawals](/api/reference/withdrawals#get-withdrawals)
* [GET /verifications](/api/reference/verifications#get-verifications)


# Errors

Error handling and codes from Public Mint's APIs.

Error codes in Public Mint correspond to standard HTTP responses indicating success or failure of requests to the API. As a general rule, this is what each code means:

| Error Code | Meaning                                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| 2xx        | Success                                                                                                                |
| 4xx        | Error on the client's side (usually due to problems with the provided information/parameters                           |
| 5xx        | Error on Public Mint's servers. These cases are rare and you should contact us in case you get a persistent 5xx error. |

###


# Core Resources

Browse v0.2 of our Public API resources

Core resources accessible via our APIs are described in detail in the corresponding endpoint section:

* [Documents resource](/api/reference/documents)
* [Deposits resource](/api/reference/deposits)
* [Verifications resource](/api/reference/verifications)
* [Withdrawals resource](/api/reference/withdrawals)
* [Identities resource](/api/reference/identities)
* [Identity relations resource](/api/reference/identity-relations)

### Postman collection

We've prepared a JSON file with the entire API collection so that you can import and test with an app such as Postman:

{% file src="/files/-MaTbc\_1Wpr-dbQavBC7" %}
Postman Collection
{% endfile %}


# Webhooks

In some cases (see examples below), we will send webhooks to the configured link associated to your partner account.&#x20;

Some of the event that will send a webhook are:

* Identity updates;
* Identity KYC updates;
* Transaction updates;
* Activated operations;
* etc.

### Activated operations

When an identity reaches a KYC status that is required for an operation to be activated, a webhook will be sent with the following information:

```
data: {
   operations: [{
      action: 'create',
      code: 'deposit:wire'
   }]
},
type: 'operationActivated'
```

### Identity verification created

When a KYC verification is created for a specific identity, a webhook will be sent with the following information:

```
data: {
   identityId: 'ab86bab9-e479-4dcf-8e29-264d355d1d36',
   verificationId: '9776d638-dbbe-4546-9d1f-264e7472b84e'
},
type: 'identityVerificationCreated'
```

### Identity verification updated

When a KYC verification is updated for a specific identity, a webhook will be sent with the following information:

```
data: {
   identityId: 'ab86bab9-e479-4dcf-8e29-264d355d1d36',
   verificationId: '9776d638-dbbe-4546-9d1f-264e7472b84e'
},
type: 'identityVerificationUpdated'
```

### Identity exception raised

When an exception is raised in the KYC of an identity, a webhook will be sent with the following information:

```
data: {
   exceptions: ['manual_review_required'],
   identityId: '9776d638-dbbe-4546-9d1f-264e7472b84e'
},
type: 'identityExceptionRaised'
```


# Getting started

An Ethereum-based blockchain, modified and optimized to natively run on fiat.

Cornerstone of the entire system, Public Mint's **blockchain** is an implementation of Ethereum with a few key functional differences to make it ideally suited for fiat.&#x20;

| Feature             | Ethereum                   | Public Mint               |
| ------------------- | -------------------------- | ------------------------- |
| New tokens          | Mining                     | Fiat deposits             |
| Gas model (fees)    | Paid in ETH                | Paid in fiat              |
| Consensus mechanism | Proof-of-Work              | Proof-of-Authority        |
| Block Validator ID  | Anonymous, not accountable | Public, fully accountable |

Besides being accessible indirectly via APIs and our Web Wallet, our blockchain is open and, well, *public* - anyone can join and is free to transact.&#x20;

### New tokens

There are no miners in Public Mint. Supply increases or decreases pending confirmation of fiat deposits by custodians. Token creation is mediated by Public Mint, with fiat delivered straight to depositors' wallets. Tokenized fiat is burned by Public Mint following withdrawal initiation by custodian partners.

### Fiat Gas model

The native currency in the Public Mint blockchain is tokenized fiat. There is no native cryptocurrency (like Ether) with which to pay for transaction fees.

Tokenized fiat is managed by a smart contract and behaves like an Ethereum ERC-20 token instead of Ether. This means that all transactions within Public Mint go through a smart contract and require a contract data payload.

### Consensus mechanism

Public Mint uses the [IBFT 2.0 Proof-of-Authority](https://besu.hyperledger.org/en/stable/HowTo/Configure/Consensus-Protocols/IBFT/) protocol, which is Byzantine fault tolerant and completely forkless. IBFT 2.0 allows for immediate transaction finality and a substantially higher throughput than Ethereum’s Proof-of-Work.

### Network nodes

Public Mint nodes run a customized version of [Hyperledger Besu](https://www.hyperledger.org/projects/besu), an open-source, enterprise-grade Ethereum client. Like Hyperledger Besu, our client offers a familiar JSON-RPC interface, granular permissions, and a stable consensus mechanism.

#### Validator nodes vs. full nodes

Validator nodes are full nodes that are authorized by the protocol to pool transactions into a block and subsequently add it to the chain, collecting transaction fees in the process. These are the equivalent to miners in Ethereum or Bitcoin.

Full nodes can't add new blocks. However, these nodes strengthen the network by verifying that transactions in each new block added by validators respect the consensus rules, ensuring validators remain honest. In addition to that, all Public Mint validators are known to the network and can be held accountable in case of misconduct.

### Ethereum Compatibility

Our client can be accessed via JSON-RPC, same as Ethereum. This means you can access our blockchain with the help of libraries such as [web3.js](https://github.com/ethereum/web3.js/), and (to a certain extent) apps like MyCrypto or Metamask.

Visit the [blockchain integration ](/api/connecting)section for the full instructions on how to communicate directly with the blockchain.


# Transacting

Using the Public Mint blockchain

Transactions in the Public Mint blockchain are quite similar to Ethereum, with one key difference: for now the USD token  is the same as native blockchain token.&#x20;

Read on to learn your way around the basics.

{% hint style="success" %}

### What you'll need

* [Node.js](https://nodejs.org/en/download/)
* [Web3.js](https://github.com/ethereum/web3.js/)
* [PublicMint-web3.js](https://public-mint-community.gitlab.io/publicmint-web3.js/tutorial-QuickStart.html)
  {% endhint %}

{% hint style="warning" %}
Just like Ethereum, transactions in the Public Mint blockchain can either *read* or *write* to the blockchain. While read-type transactions are free, writing (i.e. changing the state) entails fees. Ethereum fees are paid in ETH. In contrast, all fees on Public Mint are **paid in&#x20;*****fiat***.
{% endhint %}

### Creating a wallet

If you haven't created a Public Mint [Web Wallet](/other-information/web-wallet) and don't have your own, then the first thing you need is a wallet. Start by connecting to a node - check the [previous section](/api/connecting#starting-your-node) to get the code.

After that, it's simple:

```javascript
const web3 = new PublicMint(2019) // test network

const {
	wallet
} = web3.pm

// Add first account

// 0x4389Af2E0515dDFe3453B1bD748aDfD5e2598cFd
const walletAccountPrivateKey1 = "0xba6cdfcc795484a9774eb98e756983da822ef3481b37d4ba649864e2d1ab4e5e";
wallet.add(walletAccountPrivateKey1);

```

And that's it - keep them safe and don't show anyone. Please DO NOT send funds into the addresses above as they are published on the internet, taken from the web3.js documentation.

### Looking up your balance

{% hint style="danger" %}

### Important

Within the code, Public Mint uses the same monetary units as Ethereum when referring to its native tokens - ***Wei*** and ***Ether***. Even though the name is the same, within the context these units represent tokenized fiat.
{% endhint %}

Let's use PublicMint-web3.js to get the balance of a Public Mint address.&#x20;

```javascript
 const myBalance = await web3.pm.wallet.accounts.getBalance("address in wallet");
```

### Sending Funds

Here is what you need to do to send funds to another Public Mint address.&#x20;

Follow the steps above to get a wallet and check your balance. Here's the code snippet to transfer tokens:

```javascript
const {
    toToken// Convert 'USD'/'ETHER' into small blockchain unit 'wei'
} = web3.pm.utils

const transferReceipt = await web3.pm.wallet.accounts.transfer(<destinyAccount>, toToken(10))

```

### More transactions

{% hint style="info" %}
For a comprehensive list of transactions with examples, please check the [web3.js documentation](https://web3js.readthedocs.io/en/v1.2.1/)'s list of methods.
{% endhint %}


# Configuring Metamask for the Public Mint blockchain

Learn how to set up Metamask to connect to the Public Mint blockchain

{% hint style="danger" %}
**WARNING**: DO NOT send ETH or ERC-20 tokens directly from Ethereum to Public Mint, and DO NOT send assets directly from Public Mint to Ethereum. You may LOSE YOUR FUNDS!
{% endhint %}

### What is Metamask?

[Metamask](https://metamask.io/) is a popular Ethereum wallet and perhaps the most widely used gateway to interact with decentralized applications across the Ethereum blockchain (and many others, like BSC, RSK, xDAI, etc).

The Public Mint blockchain is based on Ethereum and fully EVM-compatible, and thus you can configure Metamask to interact with any DApps that run on Public Mint.

### What can I use Metamask for?

Metamask has basic wallet functionality, meaning you can send, receive and store tokens.

But perhaps most importantly, Metamask allows you to interact with DApps that run on top of the blockchain, (like decentralized exchanges, marketplaces, or any other smart-contract-based application) securely spending or receiving assets.

### Configuring Metamask for the Public Mint Mainnet

**1. Install the Metamask extension on your browser**. Make sure you're downloading it from a legitimate source (like the Chrome Web Store) and that the developer is metamask.io

![](/files/-MiWIgsgZtaRpEdqydC-)

**2. Click on the fox icon at your browser's toolbar.** Create a wallet if you haven't got one yet. Choose a strong password and make sure you store the seed words somewhere safe.

**3. Click on the network name on the top drop-down link**.&#x20;

<div align="left"><img src="/files/-MiWKJkuMcc4Zpd7DJ5L" alt=""></div>

**4. Scroll down to the bottom of the list and select the "Custom RPC" option.**

<div align="left"><img src="/files/-MiWKDXwVX90KAySwIfh" alt=""></div>

**5. Under&#x20;*****Network*****, fill the form with the following details:**

**Network Name** => Public Mint Mainnet\
**New RPC URL** => <https://rpc.publicmint.io:8545/\\>
**Chain ID** => 2020\
**Currency Symbol** => USD\
**Block Explorer URL** => <https://explorer.publicmint.io/>

<div align="left"><img src="/files/-MiWL36Gl945YaHAG7qg" alt=""></div>

**6. Save your selection and click the&#x20;*****Add network*****&#x20;button to finish.**&#x20;

<div align="left"><img src="/files/-MiWLkCZ8l2JRaBV92Wr" alt=""></div>

That's it! You've successfully configured Metamask to use with the Public Mint Mainnet blockchain.

<div align="left"><img src="/files/-MiWLvmEosuvPIkYLeMu" alt=""></div>

### Configuring Metamask for the Public Mint Testnet

To configure Metamask to the Public Mint Testnet blockchain, simply follow the steps above and use the following parameters when adding a new network:

**Network Name** => Public Mint Testnet\
**New RPC URL** => <https://rpc.tst.publicmint.io:8545/\\>
**Chain ID** => 2019\
**Currency Symbol** => USD\
**Block Explorer URL** => <https://explorer.tst.publicmint.io/>

### Adding MINT token to MetaMask

{% hint style="success" %}
**MAINNET MINT token contract address**

`0xC312642DaD4490D7f351391b85488d34778E9667`
{% endhint %}

{% hint style="info" %}
**TESTNET MINT token contract address**

`0xf8b10a9527d542ef7Fa32a0f8E556Ab5c050dd6c`
{% endhint %}


# Interoperability \[WIP]

Work in progress.

(WIP)


# Public Mint Wallet

Learn how to use our Web Wallet to make or receive fiat payments

The Public Mint wallet allows users to directly manage their existing funds in a fully decentralized manner.&#x20;

Our wallet connects directly to the Public Mint blockchain and allows any address to send and receive funds from another. It also connects with the centralized parts of our system, allowing users to go through KYC and initiate [deposits](/api/funding/deposit-wire) and [withdrawals](/api/funding/deposit-wire).

<div align="center"><img src="/files/-LtzOqoHeE4_9cU_fEYm" alt="Public Mint Wallet Welcome page"></div>


# Users and Accounts

There are two broader categories of Public Mint user accounts. You can access main functionalities as either an individual user or as a commercial partner.

{% hint style="warning" %}
Transactions and processes that concern moving funds into or out of the blockchain (including ancillary ones like identity management and KYC/AML) can only be accessed with a Public Mint account, either as *user* or *partner*.
{% endhint %}

As an **individual user**, you can access the Wallet and use it to make deposits/withdraw funds from the network. The only requirement is to pass a KYC process, which is conducted right on the Public Mint platform. You can also use your account on the Widget to deposit funds to any dApp or service that integrates the Widget.&#x20;

As a **partner** you can obtain and manage keys that give access to our public APIs, allowing you to build integrations between your platform and Public Mint. You'll also have access to the Partner's Portal where you can generate and manage API keys. Finally, depending on your business model, as a partner you can create and manage multiple sub-accounts on behalf of your customers.

Please contact us to find out how to become a [partner](/partners).

### Functionalities

Our [public APIs](/api/reference) give you access to all functionalities you need to build your integration, whatever your use case may be. We've put together a [development quick start](/api/identities) guide to get you up and running in no time.