Skip to content
GitHub

Create a grant request

Before a client can call the Open Payments API, it must request/receive a grant from the appropriate authorization server. The request must indicate the resource type the client intends to work with and the actions the client wants to take at the resource server.

These code snippets enable a client to request a grant for the incoming-payment, quote, and outgoing-payment resource types. Each request includes all valid actions the client can take for the resource type.

Before you begin

We recommend creating a wallet account on Rafiki.Money, a test wallet provider that’s part of the Interledger testnet. Creating an account allows you to test your client against the Open Payments API using an ILP-enabled wallet funded with play money.

Request an incoming payment grant

Additional configuration

Add "type": "module" to package.json

Add the following to tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022"
  }
}

Get started

Import dependencies

import {
  createAuthenticatedClient,
  isPendingGrant,
} from "@interledger/open-payments";

Initialize Open Payments client

const client = await createAuthenticatedClient({
  walletAddressUrl: WALLET_ADDRESS,
  privateKey: PRIVATE_KEY_PATH,
  keyId: KEY_ID,
});

Get wallet address information

const walletAddress = await client.walletAddress.get({
  url: WALLET_ADDRESS,
});

Request incoming payment grant

const grant = await client.grant.request(
  {
    url: walletAddress.authServer,
  },
  {
    access_token: {
      access: [
        {
          type: "incoming-payment",
          actions: [
            "list",
            "list-all",
            "read",
            "read-all",
            "complete",
            "create",
          ],
        },
      ],
    },
  },
);

Check grant state

if (isPendingGrant(grant)) {
  throw new Error("Expected non-interactive grant");
}

Output

console.log("INCOMING_PAYMENT_ACCESS_TOKEN =", grant.access_token.value);
console.log(
  "INCOMING_PAYMENT_ACCESS_TOKEN_MANAGE_URL = ",
  grant.access_token.manage,
);

Run tsx path/to/directory/index.ts.

View full source

Request a quote grant

Additional configuration

Add "type": "module" to package.json

Add the following to tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022"
  }
}

Get started

Import dependencies

import {
  createAuthenticatedClient,
  isPendingGrant,
} from "@interledger/open-payments";

Initialize Open Payments client

const client = await createAuthenticatedClient({
  walletAddressUrl: WALLET_ADDRESS,
  privateKey: PRIVATE_KEY_PATH,
  keyId: KEY_ID,
});

Get wallet address information

const walletAddress = await client.walletAddress.get({
  url: WALLET_ADDRESS,
});

Request quote grant

const grant = await client.grant.request(
  {
    url: walletAddress.authServer,
  },
  {
    access_token: {
      access: [
        {
          type: "quote",
          actions: ["create", "read", "read-all"],
        },
      ],
    },
  },
);

Check grant state

if (isPendingGrant(grant)) {
  throw new Error("Expected non-interactive grant");
}

Output

console.log("QUOTE_ACCESS_TOKEN =", grant.access_token.value);
console.log("QUOTE_ACCESS_TOKEN_MANAGE_URL = ", grant.access_token.manage);

Run tsx path/to/directory/index.ts.

View full source

Request an outgoing payment grant

In Open Payments, an outgoing payment grant must be interactive. An interactive grant requires interaction from a user, typically a client’s end-user, before the grant can be issued.

Additional configuration

Add "type": "module" to package.json

Add the following to tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022"
  }
}

Get started

Import dependencies

import {
  createAuthenticatedClient,
  isPendingGrant,
} from "@interledger/open-payments";

Initialize Open Payments client

const client = await createAuthenticatedClient({
  walletAddressUrl: WALLET_ADDRESS,
  privateKey: PRIVATE_KEY_PATH,
  keyId: KEY_ID,
});

Get wallet address information

const walletAddress = await client.walletAddress.get({
  url: WALLET_ADDRESS,
});

Request outgoing payment grant

const grant = await client.grant.request(
  {
    url: walletAddress.authServer,
  },
  {
    access_token: {
      access: [
        {
          identifier: walletAddress.id,
          type: "outgoing-payment",
          actions: ["list", "list-all", "read", "read-all", "create"],
          limits: {
            debitAmount: DEBIT_AMOUNT,
            receiveAmount: RECEIVE_AMOUNT,
          },
        },
      ],
    },
    interact: {
      start: ["redirect"],
      finish: {
        method: "redirect",
        uri: "http://localhost:3344",
        nonce: NONCE,
      },
    },
  },
);

Check grant state

if (!isPendingGrant(grant)) {
  throw new Error("Expected interactive grant");
}

Output

console.log("Please interact at the following URL:", grant.interact.redirect);
console.log("CONTINUE_ACCESS_TOKEN =", grant.continue.access_token.value);
console.log("CONTINUE_URI =", grant.continue.uri);

View full source

References