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