After executing the storeSchema call in the API Explorer, see the Schema you created in the Schemas tab of the dashboard.

Create a Ledger for the app using the createLedger mutation.

mutation QuickstartCreateLedger(
  $ik: SafeString!
  $ledger: CreateLedgerInput!
  $schema: SchemaMatchInput
) {
  createLedger(
    ik: $ik, 
    ledger: $ledger, 
    schema:$schema
  ) {
    ... on CreateLedgerResult {
      ledger {
        ik
        name
        created
        schema {
          key
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}

The schema.key field is set to quickstart-schema so the Ledger is created using the Schema stored by the previous API call.

{
  "ik": "quickstart-ledger",
  "ledger": {
    "name": "Quickstart Ledger"
  },
  "schema": {
    "key": "quickstart-schema"
  }
}

Use the addLedgerEntry mutation to post Ledger Entries.

mutation QuickstartAddLedgerEntry(
  $ik: SafeString!
  $entry: LedgerEntryInput!
) {
  addLedgerEntry(
    ik: $ik,
    entry: $entry,
  ) {
    ... on AddLedgerEntryResult {
      entry {
        type
        created
        posted
      }
      lines {
        amount
        key
        description
        account {
          path
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}

Start with user_funds_account.

{
  "ik": "fund-user-1-account",
  "entry": {
    "type": "user_funds_account",
    "posted": "1234-11-11T13:00:00.000Z",
    "ledger": {
      "ik": "quickstart-ledger"
    },
    "parameters": {
      "funding_amount": "10000",
      "user_id": "user-1"
    }
  }
}

The important fields in an addLedgerEntry call are type and parameters. For details on other fields, check out Post Ledger Entries.

• entry.type is set to user_funds_account, defined in the Schema.
• entry.parameters contains a key/value pair of all the parameters defined in the Schema. The funding_amount parameter sets the Ledger Line amounts and the user_id parameter sets the Ledger Account path. Since the user account is a template, the Ledger Account is created on demand.

After funding the first user, change the parameter values and re-run the mutation to create another funded user account.

{
  "ik": "fund-user-2-account",
  "entry": {
    "type": "user_funds_account",
    "posted": "1234-11-11T13:00:00.000Z",
    "ledger": {
      "ik": "quickstart-ledger"
    },
    "parameters": {
      "funding_amount": "6000",
      "user_id": "user-2"
    }
  }
}

You can then try the p2p_transfer Ledger Entry by setting type to p2p_transfer and providing the appropriate parameters from the Schema.

{
  "ik": "p2p-transfer",
  "entry": {
    "type": "p2p_transfer",
    "posted": "1234-12-11T13:00:00.000Z",
    "ledger": {
      "ik": "quickstart-ledger"
    },
    "parameters": {
      "transfer_amount": "5000",
      "from_user_id": "user-1",
      "to_user_id": "user-2"
    }
  }
}

With accounts funded and a transfer made, query a Ledger Account's balance using the ledgerAccount query.

query QuickstartGetBalance (
  $account: LedgerAccountMatchInput!
) {
    ledgerAccount(ledgerAccount: $account) {
      path
      name
      type
      ownBalance(consistencyMode: use_account)
      created
      currency {
        code
      }
  }
}

{
  "account": {
    "path": "liabilities/users:user-1/available",
    "ledger": {
      "ik": "quickstart-ledger"
    }
  }
}

Try changing path to assets/banks/user-cash or liabilities/users:user-2/available to query the other Ledger Accounts.

Look in the dashboard to see the Ledger, Ledger Accounts and Ledger Entries you've created.

Now that you've created a demonstrative Ledger for this p2p app, model your own product's flow of funds and build your own Ledger. To do that, continue to the next section, Design your Ledger.

A Ledger Account has a balance. Changes to a Ledger Account's balance are called Ledger Lines.

There are four types of Ledger Accounts, split into two layers:

State Ledger Accounts track your product's financial relationships with your bank, payment systems and users. Balance Sheets are a report of State Ledger Account balances.

Change Ledger Accounts track when and how your product makes a profit or loss. They produce Income Statements.

Within a Schema, the chartOfAccounts key contains a nested tree of Ledger Accounts, up to a maximum depth of 10:

{
  "schema": {
    "chartOfAccounts": {
      "accounts": [
        {
          "key": "banks",
          "type": "asset",
          "children": [
            {
              "key": "bank",
              "children": [
                {"key": "user-cash"},
                {"key": "reserve"}
              ]
            }
          ]
        }
      ]
    }
  }
}

Ledger Accounts that share a parent require a unique key, but the same key can be used in different parts of the tree.

For some Ledger Accounts, you must set additional properties:

• linkedAccount enables reconciliation with an external system
• template allows multiple instances to be created on demand
• currencyMode configures the account's currency mode, single or multi
• consistencyConfig configures the whether the Ledger Account's balances and Ledger Lines are strongly or eventually consistent

A Ledger Entry is a single update to a Ledger. Define a Ledger Entry type in your Schema for every financial event in your product and bank.

A Ledger Entry must be balanced, which means it follows the Accounting Equation.

How you balance a Ledger Entry depends upon its net effect to the Ledger's balances.

When the net change to the State Ledger Accounts is zero, the financial event being recorded did not change the net worth of the business. In this example, an increase to an asset account is balanced by an increase in a liability account:

{
  "ledgerEntries": {
    "types": [
      {
        "type": "user_funds_account",
        "description": "Funding {{user_id}} for {{funding_amount}}.",
        "lines": [
          {
            "key": "funds_arrive_in_bank",
            "account": { 
              "path": "assets/banks/user-cash"
            },
            "amount": "{{funding_amount}}"
          },
          {
            "key": "increase_user_balance",
            "account": { 
              "path": "liabilities/users:{{user_id}}/available"
            },
            "amount": "{{funding_amount}}"
          }
        ]
      }
    ]
  }
}

When the net change to the State Ledger Accounts is non-zero, the financial event being recorded made a profit or loss. In this example, a difference in asset and liability accounts is balanced by an increase in an income account.

{
  "schema": {
    "ledgerEntries": {
      "types": [
        {
          "type": "withdrawal",
          "description": "{{user_id}} withdraws {{withdrawal_amount}}",
          "lines": [
            {
              "key": "funds_leave_bank",
              "account": {
                "path": "assets/banks/user-cash"
              },
              "amount": "-{{withdrawal_amount}} + {{instant_fee}}"
            },
            {
              "key": "decrease_user_balance",
              "account": {
                "path": "liabilities/users:{{user_id}}/available"
              },
              "amount": "-{{withdrawal_amount}}"
            },
            {
              "key": "record_instant_payout_income",
              "account": {
                "path": "income/fees/instant_payouts"
              },
              "amount": "{{instant_fee}}"
            }
          ]
        }
      ]
    }
  }
}

The fragment CLI includes a Ledger designer to create, visualize and simulate your Schema.

To install the CLI, run:

brew tap fragment-dev/tap

brew install fragment-dev/tap/fragment-cli

To write an example Schema to ./fragment.jsonc run:

fragment init

To start the Ledger designer run:

fragment start

The Ledger designer creates a visualization of the example Schema. Whenever you edit the fragment.jsonc file, the Ledger designer updates to reflect your changes.

While developing locally, use the fragment CLI. See the installation instructions if you don't already have the CLI.

First, authenticate your local environment:

fragment login

Second, store your Schema:

fragment store-schema

Third, create the Ledger:

fragment create-ledger \
--name "sample ledger" \
--ik "ledger-1" \
--schema "sample-schema"

You can use the same Schema to create multiple Ledgers. Many applications create one Ledger for each development environment.

You can integrate the CLI commands into your CI/CD pipeline to automatically deploy your Ledger.

Use env vars with fragment login to re-use it across environments.

export FRAGMENT_CLIENT_ID="fake-client-id"
export FRAGMENT_CLIENT_SECRET="fake-client-secret"
export FRAGMENT_API_URL="https://api.us-west-2.fragment.dev/graphql"
export FRAGMENT_OAUTH_URL="https://auth.us-east-2.fragment.dev/oauth2/token"
export FRAGMENT_OAUTH_SCOPE="https://api.us-east-2.fragment.dev/*"

fragment login \
  --client-id ${FRAGMENT_CLIENT_ID} \
  --client-secret ${FRAGMENT_CLIENT_SECRET} \
  --api-url ${FRAGMENT_API_URL} \
  --oauth-url ${FRAGMENT_OAUTH_URL} \
  --oauth-scope ${FRAGMENT_OAUTH_SCOPE}

Similar to logging in, when storing the Schema, use env vars for your Links. The CLI finds and replaces ${env vars} in your Schema with the values from your environment before calling the storeSchema API.

EXTERNAL_ACCOUNT_ID="external-account-id" \
  fragment store-schema

If you are creating a Ledger for each of your users, call the storeSchema and createLedger APIs directly from your product.

Call storeSchema to store a Schema. Depending on your use case, you may share one Schema for all your users, or create a Schema per user.

mutation QuickstartStoreSchema($schema: SchemaInput!) {
  storeSchema(schema: $schema) {
    ... on StoreSchemaResult {
      schema {
        key
        name
        version {
          version
          created
          json
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}

{
  "schema": {
    "key": "quickstart-schema",
    "name": "Quickstart Schema",
    "chartOfAccounts": {
      "defaultCurrency": {
        "code": "USD"
      },
      "defaultCurrencyMode": "single",
      "accounts": [
        {
          "key": "assets",
          "type": "asset",
          "children": [
            {
              "key": "banks",
              "children": [
                {
                  "key": "user-cash"
                }
              ]
            }
          ]
        },
        {
          "key": "liabilities",
          "type": "liability",
          "children": [
            {
              "key": "users",
              "template": true,
              "consistencyConfig": {
                "ownBalanceUpdates": "strong"
              },
              "children": [
                {
                  "key": "available"
                },
                {
                  "key": "pending"
                }
              ]
            }
          ]
        },
        {
          "key": "income",
          "type": "income"
        },
        {
          "key": "expense",
          "type": "expense",
          "children": []
        }
      ]
    },
    "ledgerEntries": {
      "types": [
        {
          "type": "user_funds_account",
          "description": "Funding {{user_id}} for {{funding_amount}}.",
          "lines": [
            {
              "account": { "path": "assets/banks/user-cash" },
              "key": "funds_arrive_in_bank",
              "amount": "{{funding_amount}}"
            },
            {
              "account": { "path": "liabilities/users:{{user_id}}/available" },
              "key": "increase_user_balance",
              "amount": "{{funding_amount}}"
            }
          ]
        },
        {
          "type": "p2p_transfer",
          "description": "P2P of {{transfer_amount}} from {{from_user_id}} to {{to_user_id}}.",
          "lines": [
            {
              "account": {
                "path": "liabilities/users:{{from_user_id}}/available"
              },
              "key": "decrease_from_user",
              "amount": "-{{transfer_amount}}"
            },
            {
              "account": { "path": "liabilities/users:{{to_user_id}}/available" },
              "key": "increase_to_user",
              "amount": "{{transfer_amount}}"
            }
          ],
          "conditions": [
            {
              "account": {
                "path": "liabilities/users:{{from_user_id}}/available"
              },
              "postcondition": {
                "ownBalance": {
                  "gte": "0"
                }
              }
            }
          ]
        }
      ]
    }
  }
}

Create a Ledger using the createLedger mutation.

mutation QuickstartCreateLedger(
  $ik: SafeString!
  $ledger: CreateLedgerInput!
  $schema: SchemaMatchInput
) {
  createLedger(
    ik: $ik, 
    ledger: $ledger, 
    schema:$schema
  ) {
    ... on CreateLedgerResult {
      ledger {
        ik
        name
        created
        schema {
          key
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}

The schema.key field is set to the key from the storeSchema API call.

{
  "ik": "quickstart-ledger",
  "ledger": {
    "name": "Quickstart Ledger"
  },
  "schema": {
    "key": "quickstart-schema"
  }
}

FRAGMENT uses OAuth2's client credentials flow to authenticate API clients. The call requesting an access token follows the OAuth2 spec. You can use any OAuth2 library that supports the client credentials grant to retrieve the token or make an HTTP request. The flow is:

1. Create an API client in the FRAGMENT dashboard. All API Clients have full access to your workspace.
2. Note the auth endpoint URL and OAuth scope for your API Client. This is specific to the AWS region of your workspace.
3. Get a fresh access token from the token endpoint. The access token expires in 1 hour. We recommend retrieving a new token for each set of calls you make. You can generate and use multiple tokens at the same time.
4. Use that token in an Authorization header with the value Bearer {{access_token}} when calling the GraphQL API.

Your token request payload should be in x-www-form-urlencoded format, with the keys grant_type, scope and client_id.

grant_type=client_credentials&scope={{scope}}&client_id={{client_id}}

Your token request headers should contain the following, where client_credentials is the Base64-encoded version of: {{client_id}}:{client_secret}}.

{
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Basic {{client_credentials}}",
    "Accept": "*/*"
}

The response is a JSON object containing your access token.

{
    "access_token": "<access token>",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Putting it all together:

import axios from "axios";

const btoa = (str) => Buffer.from(str).toString("base64");

// credentials from the dashboard
const clientId = "2h4t0cv7qv5c9r0qgs1o3erkuk";
const secret = "superSecretClientSecret";
const scope = "https://api.us-west-2.fragment.dev/*";
const authUrl = "https://auth.us-west-2.fragment.dev/oauth2/token";

const getToken = async () => {

  // encode the client id and secret
  const auth = btoa(`${clientId}:${secret}`);
  
  // create the request body
  const data = new URLSearchParams();
  data.append("grant_type", "client_credentials");
  data.append("scope", scope);
  data.append("client_id", clientId);

  // retrieve the token
  const response = await axios.request({
    method: "POST",
    url: authUrl,
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${auth}`,
      Accept: "*/*",
    },
    data,
  });

  if (!response.data.access_token) {
    throw new Error(
      "didn't get an access token from auth endpoint"
    );
  }
  return response.data.access_token;
};

To ensure write operations are executed exactly once, all write mutations in FRAGMENT are idempotent. This lets you safely retry operations without risk of duplicate effects, so your application only needs to guarantee that it calls the API at least one time.

Mutations require you to provide a unique idempotency key (ik). For calls to reconcileTx, syncCustomAccounts and syncCustomTxs, FRAGMENT internally uses the transaction or account ID from the request as the idempotency key.

If you call the API more than once with the same ik and the same values, it executes only once. FRAGMENT ignores additional requests and returns the original response with isikReplay: true in the response.

Idempotency keys are scoped per-Ledger; if you send multiple requests with the same IK to different Ledgers, all mutations execute and return isIkReplay: false.

All successful mutation requests return a union type that represents an application error or a successful result. For example, the response type of the addLedgerEntry mutation:

union AddLedgerEntryResponse =
  AddLedgerEntryResult | BadRequestError | InternalError

When calling the API, your code should handle errors in this order:

1. Handle retryable HTTP errors. These are 429 or 5XX.
2. Handle non-retryable HTTP errors, other 4XX status codes. This typically happens if your query does not conform to the GraphQL spec, like omitting a required variable or selecting a nonexistent field. This class of error can be avoided if you use a generated, typed SDK.
3. Query the __typename field. This contains BadRequestError, InternalError or your MutationResult type.
4. Handle InternalError with retries and exponential backoff.
5. Handle BadRequestError by failing the operation.
6. Handle <Mutation>Result types such as AddLedgerEntryResult.

Here is an example of this written in Typescript:

import assert from 'assert';

type RequestParams = {
  query: string;
  variables: Record<string, unknown>;
};

const makeRequest = async ({ query, variables }: RequestParams): Promise<Response> => {
  const token = await getToken();
  return fetch('Fragment GraphQL URL', {
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables }),
  });
};

const query = '''
  mutation addLedgerEntry($ik: SafeString, $entry: LedgerEntryInput!) {
    addLedgerEntry(ik: $ik, entry: $entry) {
      __typename
      ...
    }
  }
''';
const variables = { ik: 'sample-ik', entry: {...} };

const handleRequest = (req: Response) => {
  if (req.status === 429 || req.status >= 500) {
    // Rate-limited or intermittent http failures. Retry the request.
    return handleRequest(await makeRequest({ query, variables }));
  }
  if ((req.status >= 400 || req.status < 500) && req.status !== 429) {
    // Invalid GraphQL request provided to Fragment. Handle the error.
    throw new Error('Invalid GraphQL request');
  }

  // .json() checks that it was a 200
  const response = await req.json();
  if (response.data.addLedgerEntry.__typename === 'InternalError') {
    // Retry the request in case of internal errors, with backoff.
    return handleRequest(await makeRequest({ query, variables }));
  }
  if (response.data.addLedgerEntry.__typename === 'BadRequestError') {
    // Invalid request provided to Fragment. Handle the error.
    throw new Error('Invalid API request to Fragment');
  }
  return response;
};

const response = handleRequest(await makeRequest({ query, variables }));
// Entry successfully posted to Fragment. Handle the response.
assert(response.data.addLedgerEntry.__typename === 'AddLedgerEntryResult');
handlePostedEntry(response.data.addLedgerEntry);

You can call FRAGMENT to update your Ledger with your product both synchronously and asynchronously.

To show users balances in real time, call the API synchronously. This ensures product flows block until the Ledger is updated; your users won't need to refresh to see updated balances. Sync updates can be both strongly or eventually consistent, depending on the use case. To make updates fault tolerant, implement your API calls with retries and exponential backoff.

For updates that don't need to be shown in real time, you can call the API asynchronously. This ensures your product flows don't block user activity while the balances are updated in your Ledger. Async updates are eventually consistent. A good easy pattern here is to have a table in your database that represents a call to FRAGMENT. Update this table transactionally from your product, then use an async queue that calls the API at least once for each transaction.

Linked Ledger Accounts are used for reconciling your Ledger with your external financial systems.

To define a Ledger Entry to a Linked Ledger Account, you must specify the tx of the Ledger Line. This is the ID of the transaction at the external system.

{
  "key": "linked-ledger-account-schema",
  "chartOfAccounts": {...},
  "ledgerEntries": {
    "types": [
      {
        "type": "reconciliation-type",
        "lines": [
          {
            "key": "reconciliation-line-key",
            "account": { "path": "bank" },
            "amount": "{{some_amount}}",
            "tx": {
              "externalId": "{{bank_transaction_id}}"
            }
          },
          {...other line}
        ]
      }
    ]
  }
}

To post Ledger Entries to a Linked Ledger Account, call reconcileTx instead of addLedgerEntry:

mutation ReconcileTx(
    $entry: LedgerEntryInput!
  ) {
    reconcileTx(entry: $entry) {
      __typename
      ... on ReconcileTxResult {
        entry {
          ik
          posted
          created
        }
        isIkReplay
        lines {
          amount
          currency {
            code
          }
        }
      }
      ... on Error {
        code
        message
      }
    }
  }

The query variables are the same as addLedgerEntry, except posted and ik are omitted. They are inferred from the external Tx.

{
  "entry": {
    "type": "reconciliation-type",
    "ledger": {
      "ik": "ledger-ik"
    },
    "parameters": {
      "bank_transaction_id": "tx_1234"
    }
  }
}

Read more about creating and using Linked Ledger Accounts in Reconcile transactions.

If a Ledger Account is in currencyMode: multi, you must specify the currency of the Ledger Lines posted to it.

{
  "key": "schema-key",
  "chartOfAccounts": {...},
  "ledgerEntries": {
    "types": [
      {
        "type": "user_funds_account",
        "description": "Funding {{user_id}} for {{funding_amount}}",
        "lines": [
          {
            "account": { "path": "assets/banks/user-cash" },
            "key": "funds_arrive_in_bank",
            "amount": "{{funding_amount}}",
            "currency": {
              "code": "USD"
            }
          },
          {
            "account": { "path": "liabilities/users:{{user_id}}/available" },
            "key": "increase_user_balance",
            "amount": "{{funding_amount}}",
            "currency": {
              "code": "USD"
            }
          }
        ]
      }
    ]
  }
}

Read more about how to implement a product that handles multiple currencies in Handle currencies.

Ledger Entry conditions are rules defined in your Schema used to manage concurrency and enforce correctness within your Ledger. If a condition is not met, the Ledger Entry is not posted and the mutation throws a BadRequestError.

Conditions are defined in the Schema:

{
  "type": "user_withdraws_funds",
  "description": "{{user_id}} withdraws for {{withdraw_amount}}",
  "lines": [
    {
      "account": { "path": "assets/banks/user-cash" },
      "key": "funds_leave_bank",
      "amount": "-{{withdraw_amount}}"
    },
    {
      "account": { "path": "liabilities/users:{{user_id}}/available" },
      "key": "decrease_user_balance",
      "amount": "-{{withdraw_amount}}"
    }
  ],
  "conditions": [
    {
      "account": {
        "path": "liabilities/users:{{user_id}}/available"
      },
      "postcondition": {
        "ownBalance": {
          "gte": "0"
        }
      }
    }
  ]
}

Read more about using Ledger Entry Conditions in Configure consistency.

You can define a Ledger Entry whose Ledger Lines are defined at runtime.

This can be useful if you're building a product where your end user, not you, defines the Ledger Entry structure. This is common for FRAGMENT users offering accounting services to their users.

To support runtime-defined Ledger Entries, omit the lines field in the Schema.

{
  "type": "runtime_entry",
  "description": "Runtime-defined ledger entry"
}

Then, set the lines field when posting the Ledger Entry using addLedgerEntry or reconcileTx:

mutation AddRuntimeLedgerEntry(
  $ik: SafeString!
  $entry: LedgerEntryInput!
) {
  addLedgerEntry(
    ik: $ik,
    entry: $entry
  ) {
    ... on AddLedgerEntryResult {
      entry {
        type
        created
        posted
      }
      lines {
        amount
        key
        description
        account {
          path
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}

{
  "ik": "add-arbitrary-ledger-entry",
  "entry": {
    "type": "runtime_entry",
    "lines": [
        {
          "account": { "path": "assets/banks/user-cash" },
          "key": "funds_arrive_in_bank",
          "amount": "100"
        },
        {
          "account": { "path": "liabilities/users:test-user/available" },
          "key": "increase_user_balance",
          "amount": "100"
        }

    ]
  }
}

After you set up the Link, create Linked Ledger Accounts, accounts in your Ledger that map 1:1 with accounts at your external financial system.

To define a Linked Ledger Account, set linkedAccount on a Ledger Account in your Schema:

{
  "chartOfAccounts": {
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset",
        "children": [{
          "key": "operating",
          "name": "Operating Bank",
          "linkedAccount": {
            "linkId": "some-link-id",
            "externalId": "bank-account-1"
          }
        }]
      }
    ]
  }
}

The linkId comes from the Link you create in the dashboard. The externalId is the ID of the account at your external financial system.

The CLI automatically replaces variables with ${ENV_VAR} syntax when running fragment store-schema. This lets you use different External Accounts per environment:

{
  "chartOfAccounts": {
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset",
        "children": [{
          "key": "operating",
          "name": "Operating Bank",
          "linkedAccount": {
            "linkId": "${BANK_LINK_ID}",
            "externalId": "${BANK_ACCOUNT_ID}"
          }
        }]
      }
    ]
  }
}

To create a Linked Ledger Account that is part of a Ledger Account template, parameterize the linkedAccount field:

{
  "chartOfAccounts": {
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset",
        "children": [{
          "key": "operating",
          "name": "Operating Bank",
          "template": true,
          "linkedAccount": {
            "linkId": "{{BANK_LINK_ID}}",
            "externalId": "{{BANK_ACCOUNT_ID}}"
          }
        }]
      }
    ]
  }
}

These parameters are then required when posting a Ledger Entry to a Linked Ledger Account. This can be useful if you're creating bank accounts per customer, for example.

Transactions at your external financial system are initiated in one of two ways:

• You initiate a payment by calling their API.
• You are notified by the external system that a transaction has occurred. This can happen via webhook, by polling their API, or receiving a periodic transaction report.

Once a transaction occurs, you need to sync it with your FRAGMENT Ledger.

If you're using a Native Link, FRAGMENT automatically syncs transactions. You can skip ahead to Reconcile transactions.

If you're using a Custom Link, your sync process should call syncCustomTxs. Your sync process can periodically enumerate transactions in your external system or be triggered by webhook.

You may also want to sync and reconcile when your product makes a payment. You should only sync transactions that are settled, not pending or declined.

Once you have a set of transactions to sync, call syncCustomTxs:

mutation SyncTransactions(
  $link: LinkMatchInput!
  $txs: [CustomTxInput!]!
) {
  syncCustomTxs(link: $link, txs: $txs) {
    __typename
    ... on SyncCustomTxsResult {
      txs {
        id
        externalId
        amount
        date
        description
      }
    }
    ... on Error {
      code
      message
    }
  }
}

{
  "link": { "id": "some-link-id" },
  "txs": [
    {
      "account": {
        "linkId": "some-link-id",
        "id": "bank-account-1"
      },
      "externalId": "tx-1",
      "description": "Processed ACH batch",
      "amount": "-100",
      "posted": "1968-01-01"
    },
    {
      "account": {
        "linkId": "some-link-id",
        "externalId": "bank-account-2"
      },
      "externalId": "tx-2",
      "description": "Received RTP payment",
      "amount": "100",
      "posted": "1968-01-01T16:45:00Z"
    }
  ]
}

You should ensure that externalId is a stable and unique identifier for each transaction, within the scope of its account. This identifier enforces idempotentency. This identifier is typically the ID of the transaction at the external system. Make sure you use the lowest level transaction ID available, not the ID of a higher level construct that may be linked to multiple transactions, like a payment.

Calling syncCustomTxs with a different description for an existing externalId updates the name of the External Account. amount and posted timestamp are immutable.

You can sync transactions from different accounts in the same API call, but they must all belong to the same Custom Link.

To reconcile a transaction from an external system, follow the same two-step process as when posting Ledger Entries:

1. Define the structure of the Ledger Entry in your Schema.
2. Post the Ledger Entry using the API.

Ledger Entries posting to a Linked Ledger Account must specify the Tx from the External Account tied to the Ledger Account. This lets FRAGMENT know which transaction to reconcile:

{
  "key": "schema-key",
  "chartOfAccounts": {...},
  "ledgerEntries": {
    "types": [
      {
        "type": "user_funds_account_via_link",
        "description": "Funding {{user_id}} for {{funding_amount}}",
        "lines": [
          {
            "account": { "path": "assets/operating" },
            "key": "funds_arrive_in_bank",
            "tx": {
              "externalId": "{{bank_transaction_id}}"
            }
          },
          {
            "account": { "path": "liabilities/users:{{user_id}}/available" },
            "key": "increase_user_balance"
          }
        ]
      }
    ]
  }
}

Notes:

• Ledger Lines posting to a Linked Ledger Account must match 1:1 with the Tx that's being reconciled.
• bank_transaction_id represents the ID of the transaction at the external system.

Instead of calling addLedgerEntry, Linked Ledger Accounts use the reconcileTx mutation:

mutation ReconcileTx(
  $entry: LedgerEntryInput!
) {
  reconcileTx(
    entry: $entry
  ) {
    ... on ReconcileTxResult {
      entry {
        type
        created
        posted
      }
      lines {
        amount
        key
        description
        account {
          path
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}

The parameters look similar to addLedgerEntry. Specify the Ledger Entry type that you are using and provide the parameters defined in the Schema:

{
  "entry": {
    "type": "user_funding",
    "ledger": {
      "ik": "ledger-ik"
    },
    "parameters": {
      "txId": "tx_12345",
      "customerId": "customer-1"
    }
  }
}

ik and posted are optional when posting Ledger Entries with reconcileTx:

• ik: the Tx.externalId is used to ensure that reconciling a transaction is idempotent
• posted: the timestamp of the Ledger Entry is taken from the Tx to ensure the Ledger mirrors the external system

Transactions synced to FRAGMENT but not reconciled to a Ledger are considered unreconciled.

You can query unreconciled transactions in a Linked Ledger Account using the unreconciledTxs field on theLedgerAccount. It is recommended to periodically call this query to ensure your Ledger stays up to date. It can also be used to build reconciliation UIs:

query GetUnreconciledTxs (
  $ledgerAccount: LedgerAccountMatchInput!
) {
  ledgerAccount(ledgerAccount: $ledgerAccount) {
    id
    unreconciledTxs {
      nodes {
        id
        description
        amount
        externalId
        externalAccountId
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

The variables specify the path of the Linked Ledger Account you are querying and the Ledger it belongs to.

{
  "ledgerAccount": {
    "path": "assets/operating",
    "ledger": {...}
  }
}

unreconciledTxs is eventually consistent, so if you've recently transacted at a Native Link or just synced manually for a Custom Link, you may not see the transaction in the query results immediately.

Use the ledgerAccount query to look up a Ledger Account's balance.

query GetBalance(
  $ledgerAccount: LedgerAccountMatchInput!
) {
  ledgerAccount(ledgerAccount: $ledgerAccount) {
    balance
  }
}

{
  "ledgerAccount": {
    "path": "assets/bank/user-cash",
    "ledger": {
      "ik": "quickstart-ledger"
    }
  }
}

Ledger Accounts have three balances:

• ownBalance is the sum of all Ledger Lines posted to the Ledger Account, excluding Ledger Lines in child Ledger Accounts
• childBalance is the sum of all Ledger Lines posted to the children of this Ledger Account
• balance is the sum of all Ledger Lines posted to this Ledger Account and its children

query GetAggregatedBalances(
  $ledgerAccount: LedgerAccountMatchInput!
) {
  ledgerAccount(ledgerAccount: $ledgerAccount) {
    childBalance
    balance
  }
}

{
  "ledgerAccount": {
    "path": "liabilities/users"
  }
}

Balance reads are eventually consistent by default. This means that the balance may not reflect all the Ledger Lines in the account.

To read a strongly consistent balance, a Ledger Account must have its balances updated in a strongly consistent manner. This is set in the Schema on a Ledger Account's consistencyConfig:

{
  "key": "strongly-consistent-ledger-accounts",
  "name": "Strongly consistent Ledger Accounts",
  "chartOfAccounts": {
    "defaultCurrency": { "code": "USD" },
    "accounts": [
      {
        "key": "liabilities",
        "type": "liability",
        "children": [
          {
            "key": "users",
            "template": true,
            "consistencyConfig": {
              "ownBalanceUpdates": "strong"
            },
            "children": [
              {
                "key": "available",
                "consistencyConfig": {
                  "ownBalanceUpdates": "strong"
                }
              },
              {
                "key": "pending"
              },
              {
                "key": "blocked"
              }
            ]
          }
        ]
      }
    ]
  }
}

Once a Ledger Account's balance is updated consistently, set the consistencyMode on balance queries to determine the consistency of the read you issue.

query GetStronglyConsistentBalance(
    $ledgerAccount: LedgerAccountMatchInput!
) {
  ledgerAccount(ledgerAccount: $ledgerAccount) {
    ownBalance(consistencyMode: strong)
  }
}

consistencyMode can be set to:

• strong to perform a strongly consistent balance read
• eventual to perform an eventually consistent balance read
• use_account to use the value of consistencyConfig.ownBalanceUpdates when performing a balance read

{
  "ledgerAccount": {
    "path": "liabilities/users:user-1/available",
    "ledger": {
      "ik": "quickstart-ledger"
    }
  }
}

Only ownBalance can be queried with consistencyMode: strong.

Read the Configure consistency section to learn more about FRAGMENT's consistency semantics and Ledger Account consistency modes.

To query the balance of a Ledger Account at a particular point in time use the at argument:

query GetHistoricalBalances(
  $ledgerAccount: LedgerAccountMatchInput!
) {
  ledgerAccount(ledgerAccount: $ledgerAccount) {
    end_of_year: balance(at: "1969")
    end_of_month: balance(at: "1969-07")
    end_of_day: balance(at: "1969-07-21")
    end_of_hour: balance(at: "1969-07-21T02")
  }
}

If you don't specify at, you'll get the latest balance. at is supported for all balances and works granularly to the hour.

You can also query the net change on a Ledger Account over a specific reporting period. This can be useful for generating financial statements.

Similar to balances, there are three types of balance changes:

• ownBalanceChange, how much ownBalance changed
• childBalanceChange, how much childBalance changed
• balanceChange, how much balance changed

Balance change queries require you to specify a period. This can be a year, quarter, month, day or hour.

query GetBalanceChanges(
  $ledgerAccount: LedgerAccountMatchInput!
) {
  ledgerAccount(ledgerAccount: $ledgerAccount) {
    ownBalanceChange(period: "1969")
    childBalanceChange(period: "1969")
    balanceChange(period: "1969")
    currentYear: balanceChange(period: "1969")
    lastYear: balanceChange(period: "1968")
    lastYearQ4: balanceChange(period: "1968-Q4")
    lastYearDecember: balanceChange(period: "1968-12")
    lastYearChristmas: balanceChange(period: "1968-12-25")
    lastYearLastHour: balanceChange(period: "1968-12-31T23")
  }
}

You can also perform multiple balance queries using aliases.

{
  "ledgerAccount": {
    "path": "liabilities/users:user-1/available",
    "ledger": {
      "ik": "quickstart-ledger"
    }
  }
}

For Ledger Accounts in currencyMode: multi, use the currency argument to query the balance in a specific currency.

query GetMultiCurrencyBalances(
  $ledgerAccount: LedgerAccountMatchInput!
) {
  ledgerAccount(ledgerAccount: $ledgerAccount) {
    latestUSDBalance: balance(currency: { code: USD })
    latestGBPBalance: balance(currency: { code: GBP })

    USDBalanceChange:
      balanceChange(period: "1969", currency: { code: USD })
    GBPBalanceChange:
      balanceChange(period: "1969", currency: { code: GBP })
  }
}

{
  "ledgerAccount": {
    "path": "liabilities/users:user-1/available",
    "ledger": {
      "ik": "quickstart-ledger"
    }
  }
}

You can also query balances in all of a multi-currency Ledger Account's currencies, see Handle currencies.

Balance queries respect the Ledger's balanceUTCOffset when specifying periods and times. This field is specified when creating the Ledger.

• If a Ledger has an offset of -08:00, then querying balance(at: "1969-01-31") returns the balance at midnight PT on that date, or 8am on 1969-02-01 UTC.
• Querying balanceChange(period: "1969") returns the net change between 8am on 1969-01-01 UTC and 8am on 1969-01-01 UTC. This gives you the net change between midnights local time.
• Daylight savings is ignored, so every day throughout the year has exactly 24 hours.

A balance sheet reports the net worth of a business at the end of a reporting period.

query GetBalanceSheet(
  $ledgerIk: SafeString!
  $balanceAtEndOf: LastMoment!
  $accountsFilter: LedgerAccountsFilterSet!
) {
  ledger(ledger: { ik: $ledgerIk }) {
    ledgerAccounts(filter: $accountsFilter) {
      nodes {
        id
        name
        type
        balance(at: $balanceAtEndOf)
      }
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "accountsFilter": {
    "type": {
      "in": ["asset", "liability"]
    }
  },
  "balanceAtEndOf": "1969"
}

Generate a balance sheet by querying balance on all asset and liability Ledger Accounts.

Providing a LastMoment to the at parameter on balance returns the balance at the end of that period. Values provided to in operators are OR'd, so both asset and liability accounts are returned.

An income statement reports how a business's net worth changed over the course of a reporting period.

query GetIncomeStatement(
  $ledgerIk: SafeString!
  $balanceChangeDuring: Period!
  $accountsFilter: LedgerAccountsFilterSet!
) {
  ledger(ledger: { ik: $ledgerIk }) {
    ledgerAccounts(filter: $accountsFilter) {
      nodes {
        path
        name
        type
        balanceChange(period: $balanceChangeDuring)
      }
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "accountsFilter": {
    "type": {
      "in": ["income", "expense"]
    }
  },
  "balanceChangeDuring": "1969"
}

Generate an income statement by querying balanceChange on all income and expense Ledger Accounts.

Providing a Period to the period parameter on balanceChange retrieves the difference in the Ledger Account's balance between the start and end of that period.

An account statement reports how a Ledger Account changed over the course of a reporting period. It contains a Ledger Account's starting balance, ending balance and all Ledger Lines posted to it.

query GetAccountStatement(
  $accountMatch: LedgerAccountMatchInput!
  $startingBalanceAtEndOf: LastMoment!
  $endingBalanceAtEndOf: LastMoment!
  $linesFilter: LedgerLinesFilterSet!
) {
  ledgerAccount(ledgerAccount: $accountMatch) {
    path
    name
    type
    startingBalance: balance(at: $startingBalanceAtEndOf)
    endingBalance: balance(at: $endingBalanceAtEndOf)
    lines(filter: $linesFilter) {
      nodes {
        id
        key
        posted
        description
        amount
        ledgerEntryId
      }
    }
  }
}

{
  "accountMatch": {
    "ledger": {
      "ik": "ik-used-to-create-ledger"
    },
    "path": "liabilities/customer-deposits/customer:123"
  },
  "linesFilter": {
    "posted": {
      "after": "1969-07-01T00:00:00.000Z",
      "before": "1969-07-30T23:59:59.999Z"
    }
  },
  "startingBalanceAtEndOf": "1969-06",
  "endingBalanceAtEndOf": "1969-07"
}

Generate an account statement by querying for balance and lines on a Ledger Account.

Get the starting balance by passing a DateTime to the at parameter on balance. Use a GraphQL alias to make multiple balance queries within one request.

To get all Ledger Lines that were posted during the reporting period, use the filter parameter on lines. The after and before filters are inclusive, so use timestamps for the first and last moments of the reporting period.

A journal export lists all Ledger Entries posted to a Ledger during a reporting period.

query GetJournalExport(
  $ledgerIk: SafeString!
  $entriesFilter: LedgerEntriesFilterSet!
  $entriesCursor: String
) {
  ledger(ledger: { ik: $ledgerIk }) {
    ledgerEntries(filter: $entriesFilter, after: $entriesCursor) {
      nodes {
        id
        type
        posted
        description
        lines {
          nodes {
            id
            description
            account {
              name
              path
              type
            }
            amount
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "entriesFilter": {
    "posted": {
      "after": "1969-01-01T00:00:00.000Z",
      "before": "1969-03-31T23:59:59.999Z"
    }
  },
  "entriesCursor": "{{data.ledger.ledgerEntries.pageInfo.endCursor}}"
}

Generate a journal export by listing Ledger Entries. For each Ledger Entry, include its Ledger Lines and their Ledger Accounts.

This can be a long list, so query pageInfo to get a pagination cursor. It can be passed to the after parameter on ledgerEntries to page through the results.

You can configure the consistency of the Ledger Entries list query in your Ledger. To do this, set consistencyConfig at the top level of your Schema:

• Use entries: eventual for Ledgers that require high throughput but can tolerate a stale entry list
• Use entries: strong for Ledgers that have lower throughput but require strong consistency, such as those powering reconcilation dashboards

{
  "consistencyConfig": {
    "entries": "strong"
  },
  "chartOfAccounts": [...]
}

By default, all Ledgers use eventual consistency.

You can configure the consistency of balances, as well as the Ledger Lines list query, in your Ledger Account.

To configure an account's balance consistency, set consistencyConfig.ownBalanceUpdates within a Ledger Account's definition:

• Use ownBalanceUpdates: eventual for Ledger Accounts that require high throughput but can tolerate stale balances, such as those used for reporting
• Use ownBalanceUpdates: strong for Ledger Accounts that have lower throughput but require strong consistency, such as those used to authorize transactions

Similarly, to configure the consistency of an account's lines, set consistencyConfig.lines:

• Use lines: eventual for Ledger Accounts that require high throughput but can tolerate a stale line list
• Use lines: strong for Ledger Accounts that have lower throughput but require strong consistency, such as those powering transaction histories displayed to end users

{
  "accounts": [
    {
      "key": "user-balance",
      "template": true,
      "type": "asset",
      "consistencyConfig": {
        "ownBalanceUpdates": "strong",
        "lines": "eventual"
      }
    }
  ]
}

By default, all Ledger Accounts use eventual for both properties.

For low-throughput applications, setting all Ledger Accounts as strong may make implementation easier. To do this, set defaultConsistencyConfig on chartOfAccounts:

{
  "chartOfAccounts": {
    "defaultConsistencyConfig": {
      "ownBalanceUpdates": "strong",
      "lines": "strong"
    },
    "accounts": [...]
  }
}

Strongly consistent Ledger Accounts generally won't have children, but in all cases child Ledger Accounts inherit the parent's consistencyConfig setting.

To query a strongly consistent ownBalance, set consistencyMode to strong when querying the Ledger Account:

query GetOwnBalances(
  $ledgerAccount: LedgerAccountMatchInput!
) {
  ledgerAccount(ledgerAccount: $ledgerAccount) {
    ownBalance(consistencyMode: strong)
    ownBalances(consistencyMode: strong) {
      nodes {
        amount
        currency {
          code
        }
      }
    }
  }
}

By default, balance queries on all Ledger Accounts are eventually consistent.

Restrictions:

• Only ownBalance supports strongly consistent reads; balance and childBalance support only eventually consistent reads
• Querying a strongly consistent balance on an eventually consistent Ledger Account throws a GraphQL error
• You cannot combine at with consistencyMode to query strongly consistent historical balances

Entry conditions are rules defined in your Schema to manage concurrency and enforce correctness within your Ledger.

Conditions are evaluated when a Ledger Entry is posted. If a condition is not met, the Ledger Entry is not posted and the mutation returns a BadRequestError with code conditional_request_failed.

Use precondition when your application reads a balance and needs to guarantee that it hasn't changed before posting the Ledger Entry.

{
  "type": "pay-employee",
  "lines": [...],
  "conditions": [
    {
      "account": {
        "path": "bank-account"
      },
      "precondition": {
        "ownBalance": {
          "eq": "{{current_balance}}"
        }
      }
    }
  ]
}

Use postcondition to guarantee that a write never puts a Ledger Account's balance in an undesirable state.

{
  "type": "pay-employee",
  "lines": [...],
  "conditions": [
    {
      "account": {
        "path": "bank-account"
      },
      "postcondition": {
        "ownBalance": {
          "gte": "0"
        }
      }
    }
  ]
}

Restrictions:

• Ledger Accounts referenced in Entry conditions must have consistencyConfig.ownBalanceUpdates set to strong
• Entry conditions can only reference Ledger Accounts posted to in the Ledger Entry
• Linked Ledger Accounts do not support Entry conditions

You can define your own currencies to track any type of value, like rewards points, stocks or physical items.

To create a custom currency, call the createCustomCurrency mutation:

mutation CreateCustomCurrency (
    $customCurrency: CreateCustomCurrencyInput!,
) {
  createCustomCurrency(
    customCurrency: $customCurrency
  ) {
    ... on CreateCustomCurrencyResult {
      customCurrency {
        code
        customCurrencyId
        precision
        name
        customCode
      }
    }
    ... on Error {
      code
      message
    }
  }
}

{
  "customCurrency": {
    "customCurrencyId": "blue-gems",
    "precision": 0,
    "name": "Blue Gems",
    "customCode": "BLUE"
  }
}

To use a custom currency, set the customCurrencyId on the currency field of a Ledger Account and Ledger Line:

{
  "key": "...",
  "chartOfAccounts": {
    "defaultCurrencyMode": "multi",
    "accounts": [
      {
        "key": "gems-issued",
        "currencyMode": "single",
        "currency": {
          "code": "CUSTOM",
          "customCurrencyId": "blue-gems"
        }
      },
      {...}
    ]
  },
  "ledgerEntries": {
    "types": [
      {
        "type": "issue-blue-gems",
        "description": "Issue blue gems",
        "lines": [
          {
            "key": "increase-pool",
            "account": { 
              "path": "gems-issued"
            },
            "amount": "{{amount}}",
            "currency": {
              "code": "CUSTOM",
              "customCurrencyId": "blue-gems"
            }
          },
          {...other line}
        ]
      }
    ]
  }
}

Data exports are delivered approximately every 5 minutes. Each data export contains the Ledger data created or updated since the previous export.

Exports are divided by data type into three files. Each file contains newline-separated JSON, where each line represents an individual instance of the respective data type: 'LedgerEntry', 'LedgerLine' or 'LedgerAccount'.

The files use a naming scheme of {File Prefix}/{type}/day={day}/hour={hour}/{partition}.part.

Example files:

• Ledger Entry
• Ledger Line
• Ledger Account

To enable data export, first create an S3 bucket. No special settings are required, but take note of the bucket name and AWS region.

Once the bucket exists, navigate to the Settings -> S3 Exports subsection of the FRAGMENT dashboard, and follow the instructions to create a new export. You need to provide:

• S3 Bucket Name, the name of the S3 bucket in AWS.
• S3 Bucket Region, the AWS region of the bucket created in the previous step (for example, us-east-1).
• Export Name, a name for this export. This is for display purposes only.
• File Prefix (optional), the path where exports are stored. If no file prefix is provided, exports are stored in the bucket root.

The instructions in the dashboard include applying an IAM policy to your bucket. Depending on how you manage your infrastructure, this may take some time, so the onboarding flow in the dashboard can be restarted at any time.

Once you've onboarded your data export, the dashboard lets you test the connection by writing a sample file to test/testLedgerEntry.part in your bucket. The test result can be:

• Policy Not Applied, FRAGMENT received an authorization error. This typically means the provided IAM policy has not yet been applied within your AWS account. This may also mean the provided bucket name or region differs from the one created in the initial setup.
• Invalid Bucket Name, the provided bucket name does not exist in AWS.
• Incorrect AWS Region, the provided bucket exists in a different region than provided.
• Verified Permissions, the file was successfully written.

FRAGMENT does not remove the test file after verifying its existence.