Circlex

---

Circlex is a client libary for the Circle API, and a Circle API Server emulator. You can use Circlex's API client to get or post to the Circle API (e.g. in the sandbox, production). You can alternatively run a Circle API Emulator, that will act like a Circle server, accepting transfers, wires, managing wallet balances, and sending and receiving USDC transfers. This emulator can be run on a test-net (e.g. Goerli) or a local Ethereum net (e.g. Anvil, possibly forking Goerli).

Installation

If available in Hex, the package can be installed by adding circlex_api to your list of dependencies in mix.exs:

def deps do
  [
    {:circlex_api, "~> 0.1.9"}
  ]
end

Getting Started

API Client

To start an API client, set-up your Circlex application by specifying the Circle host, e.g.

runtime.exs

config :circlex_api,
  host: "https://api-sandbox.circle.com",
  auth: System.get_env("CIRCLE_AUTH")

Then you can run in your application:

> Circlex.API.Health.ping()
{:ok, %{message: "pong"}}

Emulator 🦦

To run the emulator, run:

mix emulator

You can specify a port, and an initial state:

mix emulator --port 3333 --load test/support/initial_state.json

State can be serialized in the emulator to a file, and loaded back on start.

Configuring the Emulator

You can specify the following environment variables to configure the emulator:

USDC_ADDRESS={address of USDC token}
USDC_HOLDER_PK={private key of USDC holder}
ETHEREUM_REMOTE_NODE={ethereum node to attach to}

The emulator expects to have the USDC_HOLDER_PK hold sufficient USDC to be able to make transfers out, otherwise they will fail. You can use a local deployment of USDC e.g. via Anvil, Hardhat or testrpc. The only requirement is that an ERC-20 token exists and the holder has sufficient funds of it. (That is, we do not mint tokens, we just take them from the holder).

Note, you use a fork of Goerli to run the emulator on, just start Anvil with:

anvil --fork-url https://goerli.infura.io/

and then specify:

USDC_ADDRESS="0x07865c6e87b9f70255377e024ace6630c1eaa37f"
USDC_HOLDER_PK={private key of USDC holder}
ETHEREUM_REMOTE_NODE="http://localhost:8085"

In a local fork, you will not need to worry about sending away your Goerli USDC.

Persisting State

Start an emulator, and then run:

curl -XPOST http://localhost:3333/circlex/save/my_state

That should save your state to state/my_state.json. You can then reload that state with:

mix emulator --load state/my_state.json

You can also persist state after every change by running:

mix emulator --persist state/my_state.json

This will load and store the state with that JSON file so it's always in sync. This is not done particularly efficiently, so buyer beware.

Documentation

Full documentation can be found at https://hexdocs.pm/circlex.

Client Features

The following APIs are supported by the API client:

• Health API
• Management API
• Encryption API
• Subscriptions API
• Channels API
• Stablecoins API
• Core - Balances API
• Core - Payouts API
• Core - Bank Accounts API
• Core - Transfers API
• Core - Addresses API
• Core - Deposits API
• Payments - Payments API
• Payments - Cards API
• Payments - Bank Accounts / Wires API
• Payments - On-chain Payments API
• Payments - Settlements API
• Payments - Chargebacks API
• Payments - Reversals API
• Payments - Balances API
• Payouts - Payouts API
• Payouts - Bank Accounts API
• Payouts - Transfers API
• Payouts - Returns API
• Accounts - Wallets API
• Accounts - Transfers API

Emulator Features

The following APIs are supported by the emulator:

• Health API
• Management API
• Encryption API
• Subscriptions API
• Channels API
• Stablecoins API (*partial)
• Core - Balances API
• Core - Payouts API
• Core - Bank Accounts API
• Core - Transfers API
• Core - Addresses API
• Core - Deposits API
• Payments - Payments API
• Payments - Cards API
• Payments - Bank Accounts / Wires API
• Payments - On-chain Payments API
• Payments - Settlements API
• Payments - Chargebacks API
• Payments - Reversals API
• Payments - Balances API
• Payouts - Payouts API
• Payouts - Bank Accounts API
• Payouts - Transfers API
• Payouts - Returns API
• Accounts - Wallets API
• Accounts - Transfers API
• Mocks (Wire) API

Additionally, the emulator has the features:

 * Payment Actor
 * Payout Actor
 * Transfer Actor

These actors follow the flows of a payment, payout or transfer from "pending" to "complete" possibly sending on-chain USDC transfers, etc, to match the role of a real Circle server.

Contributing

Create a pull request to contribute to Circlex. All contributors agree to accept the license specified in this repository for all contributions to this project. See LICENSE.md.

Note: The author generated the Circlex logo with DALL•E, OpenAI's text-to-image generation model. The image was further modified by the author.