@moneymade/connect-api

v0.1.7

Published

3 years ago

Connector to make easier integration with Moneymade open API

Downloads

0High
0Medium
0Low

Moneymade Connect API official nodejs SDK

Navigation

Installation

npm:

$ npm install @moneymade/connect-api

yarn:

$ yarn add @moneymade/connect-api

Get started

The package @moneymade/connect-api supports all MoneyMade-Connect-API endpoints. SDK requires Secret key and Api key for initialisation. These keys are different for development/production environments. Make sure you use right keys per each your environment.

NOTE: don't put yout keys into a code. Use env variable for the best practice.

import { MoneymadeSDK } from '@moneymade/connect-api';

const sdk = new MoneymadeSDK({
  secret: process.env.MONEYMADE_API_SECRET,
  apiKey: process.env.MONEYMADE_API_KEY,
});

SDK starts asynchronously, run init method to allow usage:

  await sdk.init();

Pagination

Some methods return paginated data: object contains data as array of retrieved entities and pagination info.

{
  "pagination": {
    "offset": 0, // offset for entities to be skipped
    "limit": 200 // limit per request to be retrieved
  },
  "data": [] // array with data
}

Those method applies pagintation parameters as arguments to move page backward/forward.

User API

User API allows to manipulate with accounts data. User is a container to put connected accounts and connect it via your internal user.

User object

User object contains data describes the user and connected accounts:

{
  "id": "b80b1a13-82d5-4397-a1da-29b4452905ca", // user id
  "accounts": [ // connected accounts
    {
      "id": "1a4da820-49f0-4bf5-852b-8c2a28d4b51a", // account id
      "provider": { // provider info
        "id": 9,
        "name": "Ethereum Address",
        "slug": "ethereum-address",
        "strategy": "keys",
        "logo": "https://avatars.githubusercontent.com/u/6250754?s=200&v=4"
      }
    }
  ]
}

User creation

Creating a new user requires client_user_id (it might be your internal user id) and optional email.

await moneymade.users.create({ client_user_id: 'you-internal-user-id' });

This method returns newly created user object.

User token creation

Creating a new token for user. This token is used by widget only.

// you can use userId from User Object or your internal user id
// (if internal user id was used as client_user_id on user creation)
await moneymade.users.createSession('userId');

Optionally, you can pass array of "scopes" as the second parameter scopes values are: "*", "accounts", "accounts:banking", "accounts:transactions", "accounts:holdings", "accounts:balances"

// you can use userId from User Object or your internal user id
// (if internal user id was used as client_user_id on user creation)
await moneymade.users.createSession('userId', ["accounts", "banking"]);

User retrieving

You should use user id from user object to retrive previously created user.

await moneymade.users.getOne('userId');

Method returns user object with stored accounts.

Account object

User contains accounts object. This object isn't populated via full account data (subaccount info). Full account object contains following data:

 {
   "id": "cb928ffc-b8bf-4fb5-b0e7-4612de3307c5", // account id
   "provider": { // provider info
     "id": 8,
     "name": "Bitcoin Address",
     "slug": "bitcoin-address",
     "strategy": "keys",
     "logo": "https://bitcoin.org/img/icons/logotop.svg?1630339663"
   },
   "subaccounts": [ // subaccounts info
     {
       "name": "BTC", // account name
       "currency": "BTC", // root currency for account, equals to ticker for crypto 
       "balance": "5.1704304", // balance in currency 
       "type": "cryptocurrency", // balance type, pissible value: crypto, fiat, unknown
       "fiat_balance": 22670698, // amount in cents
       "balance_updated_at": "2021-09-23T13:36:10.128Z", // ISO date when balance was changed last time
       "updated_at": "2021-09-23T13:36:10.128Z" // last account sync ISO date
     }
   ]
 }

User account retrieving

Account object is fetched by following method:

await sdk.users.getAccount({
  userId: testUserId,
  accountId: testAccountId,
});

User account removing

Use removeAccount to remove account from user:

await sdk.users.removeAccount({
  userId: 'some-user-id',
  accountId: 'some-account-id',
});

Accounts API

Account bank details object

Accounts bank details object:

{
  "account_number": "12321312",
  "holder_name": "Holders name",
  "routing_number": "24124124",
  "type": "bank",
  "balance": 0,
  "source": "plaid"
}

Accounts bank details

Get account's bank details

await sdk.accounts.getBankDetails('some-account-id');

Method returns response with array of Account bank detail Object

Account holdings object

Accounts holding object:

{
  "account_id": "test-account-id",
  "subaccount_id": "test-subaccount-id",
  "ticker": "Ticker",
  "name": "Name",
  "isin": "",
  "type": "bank",
  "amount": 0,
  "current_price":0,
  "current_amount_price":0
}

Accounts retrieve holdings

Get account's holdings

await sdk.accounts.getHoldings('some-account-id');

Method returns response with array of Account holdings object

Provider API

Provider object

Provider object describes invest or finance institution. Object contains following data:

{
  "id": 1,
  "name": "Coinbase",
  "slug": "coinbase",
  "strategy": "oauth", 
  "connector": "coinbase",
  "description": "Buy and sell cryptocurrency. Coinbase is the easiest place to buy, sell, and manage your cryptocurrency portfolio.",
  "website": "https://www.coinbase.com",
  "tags": [],
  "logo": "https://firebasestorage.googleapis.com/v0/b/benchmark-media.appspot.com/o/logos%2F1598311540327_Screen%20Shot%202020-08-24%20at%204.25.31%20PM.png?alt=media"
  }

Providers retrieving

Use following method to fetch providers.

  await moneymade.providers.getList()

Method returns array with provider objects. NOTE: Pagination will be added soon. (in Dec 5 2021).

Provider retrieving by id

Use following method to fetch provider by id.

await moneymade.providers.getOne(1);

Method returns provider object.

Currencies API

Currency object

Currency object describe currency and contains following data:

{
  "currency": "ETH", // currency ticker
  "name": "Ethereum", // readable name 
  "type": "cryptocurrency", // currency type, equals to "fiat" for fiat currencies
  "logo": null // logo url, nullable
}

Currency retrieving

await moneymade.currencies.getList();

Method returns array with currency objects

Transactions API

Transaction Object

Transaction describes changing balance in subaccount and contains following data:

{
  "id": "cd68c98c-6853-47e6-a48a-cc2c4362d971", // transaction id
  "subaccount_id": "edcddedb-f33f-42d4-a3d8-c38a58004b8a", // moneymade open api subaccount id 
  "transaction_id": "LS2BVV-LF7ZA-5HSTUK", // native transaction id
  "account_id": "c4312961-dbd9-4ff9-af43-926dc93b2cb7", // moneymade open api account id
  "amount": "2.76", // transaction amount
  "iso_currency_code": "EUR", // amount currency
  "categories": [], // array with categories
  "issued_at": "2021-08-24 06:04:01.336+00",
  "transaction_type": "sell", 
  "status": "completed",
  "created_at": "2021-11-29 11:42:36.814217+00",
  "updated_at": "2021-11-29 11:42:36.814217+00"
}

Transaction retrieving

Transaction data is returned as pages. Look at pagination for more info.

await sdk.transactions.getList({
  userId: 'some-user-id',
  accountId: 'some-account-id',
});

Method returns paginated response with transaction objects

Webhooks API

Webhook Object

Webhook object contains following data:

{
  "id": "cd68c98c-6853-47e6-a48a-cc2c4362d971", // webhook id
  "url": "http://exaple.com", // url for webhook
}

Webhook creation

Webhook creation method requires "url" parameter.

await sdk.webhooks.create('some url');

Method returns response with webhook object

Webhooks retrieving

Webhooks retrieving method requires no parameters.

await sdk.webhooks.getList();

Method returns response with array of webhook objects

Webhook retrieving

Webhook retrieving method requires "id" parameter of webhook.

await sdk.webhooks.getOne('some-webhook-id');