Omnibus

For USDF bank consortium members who are integrating with our Banking API in order to facilitate single-step Peer-to-Peer (P2P) transfers for their core banking customers, we have added program-specific endpoints that make the Banking API a one-stop-shop for facilitating multi-step transactions in a single request. These proxy the backing Omnibus USDF middleware configured for your program directly to mint, transfer and burn USDF coin.

Minting

A mint instructs your omnibus provider to create USDF coin to be distributed to a registered account.

Mint and then transfer to address

Create a mint & transfer request by specifying a mint_address and a transfer_address. This will tell the omnibus provider to mint and withdraw the amount to the specified mint_address and transfer the amount to the transfer_address.

POST /mints

{
  "id": "b005e58f-6c64-4273-98e5-4d7d67aaee33",
  "mint_address": "tp1y95akgy70pnnsa27sm0htewcdul97tra4w54n2",
  "transfer_address": "tp1w4cgw58k9qn66weqgn2n3h56jm6weyavmu873u",
  "note": "Lunch",
  "amount_coins": 2500
}

Retrieve a mint status

Fetch a mint from the API to check its status.

GET /mints/:mint_id

{
    "id": "b005e58f-6c64-4273-98e5-4d7d67aaee33",
    "mint_transaction_id": "d40356d2-6223-40f9-b028-08e2f05f08b2",
    "transfer_transaction_id": "e5f7e3ec-a949-4267-a1b5-c6a936782320",
    "transfer_address": "tp1w4cgw58k9qn66weqgn2n3h56jm6weyavmu873u",
    "mint_address": "tp1jcmzjcaz5jc9cpm8rc8yxtkftl4tq",
    "note": "Lunch",
    "amount": 2500,
    "status": "PENDING_MINT" | "PENDING_TRANSFER" | "COMPLETE",
    "created_dt": "2022-05-25T10:08:57.551811-04:00",
    "updated_dt": "2022-05-25T10:08:57.551862-04:00"
}

Burn

A burn request will instruct your omnibus provider to remove USD coin and reserve token from circulation.

Create a burn request

You can only burn an amount equal to the minimum of USD coin available at your omnibus provider.

POST /burns

{
  "id": "888aebe4-e341-446a-8e56-ac3c207b2510",
  "amount_coins": 100
}

Retrieve the status of a burn

GET /burns/:burn_id

{
  "id": "888aebe4-e341-446a-8e56-ac3c207b2510",
  "status": "PENDING" | "COMPLETE"
}

Transfer Workflow

Sender

The sender is the custodian program of the account initiating the transfer. They are aware of the mint record from the transfer and will receive transaction events corresponding to the mint from omnibus, and the transfer between users.

Mint and Transfer Sender Workflow

Recipient

The recipient is the custodian program of the account receiving funds from a P2P transfer. They receive transaction events corresponding to the transfer between users, and the redemption of USDF coin to their omnibus account.

Mint and Transfer Recipient Workflow

Events

Programs will receive Transaction Events for the corresponding mint, transfer, and redemption transactions that are part of the mint and transfer flow. The specific transaction events that programs will receive will depend on whether they are the custodian for the sender or recipient user of the transfer.

Programs initiating a mint and transfer will receive events for the mint transaction and the transfer transaction. Programs that custody an account receiving a P2P transfer will receive events for the transfer transaction and the redemption transaction.

Programs should expect two events per transaction. One when the transaction is first created in a PENDING state, and a second event once the transaction has posted and is set to a COMPLETE state.

Mint & Transfer Initiated

After a mint and transfer has been initiated programs will first receive a transaction event corresponding to the mint_transaction_id on the mint indicating the transfer of USDF coin from the omnibus provider to the transfer sender's account.

{
   "id": "dc83ffbb-9d44-4fa2-a04d-cc5b6547b106",
   "created_dt": "2022-01-02T03:04:05.123456-05:00",
   "sequence_number": 1,
   "type": "TRANSACTION_STATUS",
   "data": {
      "id": "d40356d2-6223-40f9-b028-08e2f05f08b2",
      "to": {
         "id": "38f8cd85-a80d-4ee7-ad89-818663f6caf0",
         "blockchain_address": "tp10nnm70y8zc5m8yje5zx5canyqq639j3ph7mj8p",
         "name": "Basic Checking",
         "account_details": {
            "id": "6f6554e4-0c4c-4819-a89e-7ce9a3e5120b",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "john",
               "full_name": "John Doe"
            }
         }
      },
      "status": "PENDING",
      "type: "MINT",
      "amount_coins": 25,
      "note": "Lunch",
      "createdDt": "2022-01-02T03:04:05.123456-05:00",
      "updatedDt": "2022-01-02T03:04:05.123456-05:00"
   }
}

Mint Completed

After the omnibus provider successfully mints USDF coin to the sender account an event will be created signifying that the mint transaction has completed.

{
   "id": "1b3b6ed7-1d41-4de0-8877-49f34f1f3d43",
   "created_dt": "2022-01-02T03:04:05.123456-05:00",
   "sequence_number": 2,
   "type": "TRANSACTION_STATUS",
   "data": {
      "id": "d40356d2-6223-40f9-b028-08e2f05f08b2",
      "to": {
         "id": "38f8cd85-a80d-4ee7-ad89-818663f6caf0",
         "blockchain_address": "tp10nnm70y8zc5m8yje5zx5canyqq639j3ph7mj8p",
         "name": "Basic Checking",
         "account_details": {
            "id": "6f6554e4-0c4c-4819-a89e-7ce9a3e5120b",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "john",
               "full_name": "John Doe"
            }
         }
      },
      "status": "COMPLETE",
      "type: "MINT",
      "blockchain_transaction_hash": "4E1496509078F890E2707F6B678C39E1A504E8FAC39A81DC5AA62F9CCBD6F5F2",
      "amount_coins": 25,
      "note": "Lunch",
      "createdDt": "2022-01-02T03:04:05.123456-05:00",
      "updatedDt": "2022-01-02T03:04:05.123456-05:00"
   }
}

At that time a second event will also be emitted for the transfer transaction that will send the newly minted coin to the recipient account of the transfer. This transaction will correspond to transfer_transaction_id on the mint.

{
   "id": "4b6ab045-aaa3-4391-a27b-ab0c6c5411f3",
   "created_dt": "2022-01-02T03:04:09.123456-05:00",
   "sequence_number": 3,
   "type": "TRANSACTION_STATUS",
   "data": {
      "id": "f9b5fad3-6a65-4bb8-87d1-0a9997465ee0",
      "from": {
         "id": "38f8cd85-a80d-4ee7-ad89-818663f6caf0",
         "blockchain_address": "tp10nnm70y8zc5m8yje5zx5canyqq639j3ph7mj8p",
         "name": "Basic Checking",
         "account_details": {
            "id": "6f6554e4-0c4c-4819-a89e-7ce9a3e5120b",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "john",
               "full_name": "John Doe"
            }
         }
      },
      "to": {
         "id": "4a96649b-2bf7-4cd3-aa1e-e705122c486c",
         "blockchain_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
         "name": "Basic Checking",
         "account_details": {
            "id": "6c276fe1-a172-4f5d-b46b-17579c3b451f",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "jane",
               "full_name": "Jane Smith"
            }
         }
      },
      "status": "PENDING",
      "type: "TRANSFER",
      "amount_coins": 25,
      "note": "Lunch",
      "createdDt": "2022-01-02T03:04:05.123456-05:00",
      "updatedDt": "2022-01-02T03:04:05.123456-05:00"
   }
}

The custodian program of the recipient account will receive a separate event with the same transaction metadata.

{
   "id": "b8989b43-f1a3-4f2f-b37b-b5a90d6fe4b5",
   "created_dt": "2022-01-02T03:04:09.123456-05:00",
   "sequence_number": 1,
   "type": "TRANSACTION_STATUS",
   "data": {
      "id": "f9b5fad3-6a65-4bb8-87d1-0a9997465ee0",
      "from": {
         "id": "38f8cd85-a80d-4ee7-ad89-818663f6caf0",
         "blockchain_address": "tp10nnm70y8zc5m8yje5zx5canyqq639j3ph7mj8p",
         "name": "Basic Checking",
         "account_details": {
            "id": "6f6554e4-0c4c-4819-a89e-7ce9a3e5120b",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "john",
               "full_name": "John Doe"
            }
         }
      },
      "to": {
         "id": "4a96649b-2bf7-4cd3-aa1e-e705122c486c",
         "blockchain_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
         "name": "Basic Checking",
         "account_details": {
            "id": "6c276fe1-a172-4f5d-b46b-17579c3b451f",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "jane",
               "full_name": "Jane Smith"
            }
         }
      },
      "status": "PENDING",
      "type: "TRANSFER",
      "amount_coins": 25,
      "note": "Lunch",
      "createdDt": "2022-01-02T03:04:05.123456-05:00",
      "updatedDt": "2022-01-02T03:04:05.123456-05:00"
   }
}

Transfer Completed

After provenance has processed the transfer transaction an event will be emitted marking the transaction as COMPLETE.

{
   "id": "7c861a26-45a9-4fa3-a823-b510ceeafcbc",
   "created_dt": "2022-01-02T03:04:09.123456-05:00",
   "sequence_number": 4,
   "type": "TRANSACTION_STATUS",
   "data": {
      "id": "f9b5fad3-6a65-4bb8-87d1-0a9997465ee0",
      "from": {
         "id": "38f8cd85-a80d-4ee7-ad89-818663f6caf0",
         "blockchain_address": "tp10nnm70y8zc5m8yje5zx5canyqq639j3ph7mj8p",
         "name": "Basic Checking",
         "account_details": {
            "id": "6f6554e4-0c4c-4819-a89e-7ce9a3e5120b",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "john",
               "full_name": "John Doe"
            }
         }
      },
      "to": {
         "id": "4a96649b-2bf7-4cd3-aa1e-e705122c486c",
         "blockchain_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
         "name": "Basic Checking",
         "account_details": {
            "id": "6c276fe1-a172-4f5d-b46b-17579c3b451f",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "jane",
               "full_name": "Jane Smith"
            }
         }
      },
      "status": "COMPLETE",
      "type: "TRANSFER",
      "blockchain_transaction_hash": "4E1496509078F890E2707F6B678C39E1A504E8FAC39A81DC5AA62F9CCBD6F5F5",
      "amount_coins": 25,
      "note": "Lunch",
      "createdDt": "2022-01-02T03:04:05.123456-05:00",
      "updatedDt": "2022-01-02T03:04:05.123456-05:00"
   }
}

The custodian program of the recipient account will receive a separate event with the same transaction metadata.

{
   "id": "ea8e864f-f9b9-42c9-8764-0c39656845f6",
   "created_dt": "2022-01-02T03:04:09.123456-05:00",
   "sequence_number": 2,
   "type": "TRANSACTION_STATUS",
   "data": {
      "id": "f9b5fad3-6a65-4bb8-87d1-0a9997465ee0",
      "from": {
         "id": "38f8cd85-a80d-4ee7-ad89-818663f6caf0",
         "blockchain_address": "tp10nnm70y8zc5m8yje5zx5canyqq639j3ph7mj8p",
         "name": "Basic Checking",
         "account_details": {
            "id": "6f6554e4-0c4c-4819-a89e-7ce9a3e5120b",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "john",
               "full_name": "John Doe"
            }
         }
      },
      "to": {
         "id": "4a96649b-2bf7-4cd3-aa1e-e705122c486c",
         "blockchain_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
         "name": "Basic Checking",
         "account_details": {
            "id": "6c276fe1-a172-4f5d-b46b-17579c3b451f",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "jane",
               "full_name": "Jane Smith"
            }
         }
      },
      "status": "COMPLETE",
      "type: "TRANSFER",
      "blockchain_transaction_hash": "4E1496509078F890E2707F6B678C39E1A504E8FAC39A81DC5AA62F9CCBD6F5F5",
      "amount_coins": 25,
      "note": "Lunch",
      "createdDt": "2022-01-02T03:04:05.123456-05:00",
      "updatedDt": "2022-01-02T03:04:05.123456-05:00"
   }
}

At this point another transaction event will be emitted for the redemption of USDF coin from the transfer recipient account to the consortium bank that owns the recipient account.

{
   "id": "0470ee78-a560-4d30-a7e6-88f0bfa3887d",
   "sequence_number": 3,
   "type": "TRANSACTION_STATUS",
   "created_dt": "2022-01-02T03:04:15.123456-05:00",
   "data": {
      "id": "fdb494db-c34b-4d74-8873-df0f11dc6da3",
      "from": {
         "id": "4a96649b-2bf7-4cd3-aa1e-e705122c486c",
         "blockchain_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
         "name": "Basic Checking",
         "account_details": {
            "id": "6c276fe1-a172-4f5d-b46b-17579c3b451f",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "jane",
               "full_name": "Jane Smith"
            }
         }
      },
      "status": "PENDING",
      "type: "REDEMPTION",
      "amount_coins": 25,
      "note": "Lunch",
      "createdDt": "2022-01-02T03:04:05.123456-05:00",
      "updatedDt": "2022-01-02T03:04:05.123456-05:00"
   }
}

Redemption Completed

After provenance has processed the redemption transaction an event will be emitted marking the transaction as COMPLETE.

{
   "id": "9ee0e9ce-a4d8-4c01-8b39-19f94e66cbf3",
   "sequence_number": 4,
   "type": "TRANSACTION_STATUS",
   "created_dt": "2022-01-02T03:04:15.123456-05:00",
   "data": {
      "id": "fdb494db-c34b-4d74-8873-df0f11dc6da3",
      "from": {
         "id": "4a96649b-2bf7-4cd3-aa1e-e705122c486c",
         "blockchain_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
         "name": "Basic Checking",
         "account_details": {
            "id": "6c276fe1-a172-4f5d-b46b-17579c3b451f",
            "account_type": "PROFILE_ACCOUNT",
            "profile_details": {
               "profile_type": "PERSONAL",
               "username": "jane",
               "full_name": "Jane Smith"
            }
         }
      },
      "status": "COMPLETE",
      "type: "REDEMPTION",
      "blockchain_transaction_hash": "4E1496509078F890E2707F6B678C39E1A504E8FAC39A81DC5AA62F9CCBD6F5F9",
      "amount_coins": 25,
      "note": "Lunch",
      "createdDt": "2022-01-02T03:04:05.123456-05:00",
      "updatedDt": "2022-01-02T03:04:05.123456-05:00"
   }
}

Omnibus

Minting​

Mint and then transfer to address​

Retrieve a mint status​

Burn​

Create a burn request​

Retrieve the status of a burn​

Transfer Workflow​

Sender​

Recipient​

Events​

Mint & Transfer Initiated​

Mint Completed​

Transfer Completed​

Redemption Completed​