@fiatconnect/fiatconnect-sdk

fiatconnect-sdk

A lightweight Typescript helper library for wallets or dapps to integrate with FiatConnect compliant APIs.

Basic usage

To begin, install the library from your project:

yarn add @fiatconnect/fiatconnect-sdk

Next, initialize a FiatConnectClient wherever you need to access a FiatConnect API in your codebase. See examples in the Valora wallet and FiatConnect validation tests.

From there, you can access any FiatConnect endpoint by invoking a method on the FiatConnectClient instance. There is a convenient example of a full transfer in this validation test.

Authenticated endpoints

Note that some FiatConnect endpoints require authentication before they can be accessed. You can read up on FiatConnect authentication here.

The FiatConnect SDK handles authentication by taking a signingFunction as a parameter in the FiatConnectClient constructor. The FiatConnectClient instance uses the signing function to sign a SIWE message and log in with a FiatConnect provider when:

• the login method is invoked explicitly
• any method for an endpoint that requires authentication is invoked (and the user does not already have a valid session)

Wallets may or may not wish to require a PIN every time a SIWE message is signed, or just some of the time. They may implement whatever preference they have by writing the signingFunction accordingly.

Accessing multiple FiatConnect providers

In most cases, clients will wish to integrate with multiple FiatConnect providers. However, it is worth noting that the FiatConnectClient class deals with only a single provider. This allows for more convenient separation of session cookies and provider-specific configuration data (base URL, etc.).

For an example of how to manage multiple FiatConnect providers in your codebase using the FiatConnect SDK, you may refer to the Valora wallet, which stores an object in memory mapping provider ID's to FiatConnectClient instances. Many similar possibilities exist.

Testing with a sandbox server

At time of writing, three companies offer a FiatConnect-compliant sandbox API: Valora, Alpha Fortress, and Bitmama.

If you want to test against a sandbox server that is FiatConnect-compliant, you can ask one of these companies on Discord to share API credentials with you. In particular, you will want a base URL and client API key that can be used to instantiate a FiatConnectClient.

Alternatively, if you want to make heavier use of a sandbox server (such as for CI), you can stand up your own FiatConnect-compliant sandbox using the api starter.

Running tests

yarn test

Contributing

We welcome contributions in the form of Issues and PRs. See CONTRIBUTING.md. If you have ideas for FiatConnect SDK that you'd like to discuss with other developers, you may contact us on the FiatConnect Discord.

Publishing

• Requires access to our NPM organization. Ask on FiatConnect Discord
• Make sure you are on the latest version of branch main
• Check out a release branch
• Run yarn prepublish && yarn release
• Add release notes to CHANGELOG.md
• Once code review has taken place:
  • Merge your branch
  • Run git tag vX.Y.Z && git push origin vX.Y.Z to push your tag (where X.Y.Z is the version you are trying to publish)
  • Create a release with the new tag
  • Run npm publish --public