circle

package
v0.0.0-...-9a6a6cd Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 13, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const StellarChainCode = "XLM"

Variables

View Source
var (
	ErrUnsupportedCurrency           = errors.New("unsupported Circle currency code")
	ErrUnsupportedCurrencyForNetwork = errors.New("unsupported Circle currency code for this network type")
)

AllowedAssetsMap is a map of Circle currency codes to Stellar assets, for each network type.

View Source
var DestinationAddressErrorCodes = []int{5003, 5004, 5011}

DestinationAddressErrorCodes are the error codes that indicate an issue with the destination address. If they show up when sending a payout, the Circle recipient will likely become unusable and will need to be recreated.

Circle API documentation: https://developers.circle.com/circle-mint/circle-apis-api-errors.

Functions

func ParseStellarAsset

func ParseStellarAsset(circleCurrency string, networkType utils.NetworkType) (data.Asset, error)

ParseStellarAsset returns the Stellar asset for the given Circle currency code, or an error if the currency is not supported in the SDP.

Types

type APIError

type APIError struct {
	// Code is the Circle API error code.
	Code    int              `json:"code"`
	Message string           `json:"message"`
	Errors  []APIErrorDetail `json:"errors,omitempty"`
	// StatusCode is the HTTP status code.
	StatusCode int `json:"status_code,omitempty"`
}

APIError represents the error response from Circle APIs.

func (APIError) Error

func (e APIError) Error() string

Error implements the error interface for APIError.

type APIErrorDetail

type APIErrorDetail struct {
	Error        string                 `json:"error"`
	Message      string                 `json:"message"`
	Location     string                 `json:"location"`
	InvalidValue interface{}            `json:"invalidValue,omitempty"`
	Constraints  map[string]interface{} `json:"constraints,omitempty"`
}

APIErrorDetail represents the detailed error information.

type APIType

type APIType string
const (
	APITypePayouts   APIType = "PAYOUTS"
	APITypeTransfers APIType = "TRANSFERS"
)

func AllAPITypes

func AllAPITypes() []APIType

func ParseAPIType

func ParseAPIType(messengerTypeStr string) (APIType, error)

type AccountConfiguration

type AccountConfiguration struct {
	Payments WalletConfig `json:"payments,omitempty"`
}

AccountConfiguration represents the configuration settings of an account.

type Balance

type Balance struct {
	Amount   string `json:"amount"`
	Currency string `json:"currency"`
}

Balance represents the amount and currency of a balance or transfer.

type Balances

type Balances struct {
	Available []Balance `json:"available"`
	Unsettled []Balance `json:"unsettled"`
}

Balances represents the available and unsettled balances for different currencies.

type Client

type Client struct {
	BasePath string
	APIKey   string
	// contains filtered or unexported fields
}

Client provides methods to interact with the Circle API.

func (*Client) GetAccountConfiguration

func (client *Client) GetAccountConfiguration(ctx context.Context) (*AccountConfiguration, error)

GetAccountConfiguration retrieves the configuration of the Circle Account.

func (*Client) GetBusinessBalances

func (client *Client) GetBusinessBalances(ctx context.Context) (*Balances, error)

GetBusinessBalances retrieves the available and unsettled balances for different currencies.

func (*Client) GetPayoutByID

func (client *Client) GetPayoutByID(ctx context.Context, id string) (*Payout, error)

GetPayoutByID retrieves a payout by its ID.

Circle API documentation: https://developers.circle.com/api-reference/circle-mint/payouts/get-payout.

func (*Client) GetRecipientByID

func (client *Client) GetRecipientByID(ctx context.Context, id string) (*Recipient, error)

GetRecipientByID retrieves a recipient by its ID.

Circle API documentation: https://developers.circle.com/api-reference/circle-mint/payouts/get-address-book-recipient.

func (*Client) GetTransferByID

func (client *Client) GetTransferByID(ctx context.Context, id string) (*Transfer, error)

GetTransferByID retrieves a transfer by its ID.

Circle API documentation: https://developers.circle.com/circle-mint/reference/gettransfer.

func (*Client) Ping

func (client *Client) Ping(ctx context.Context) (bool, error)

Ping checks that the service is running.

Circle API documentation: https://developers.circle.com/circle-mint/reference/ping.

func (*Client) PostPayout

func (client *Client) PostPayout(ctx context.Context, payoutRequest PayoutRequest) (*Payout, error)

PostPayout creates a new payout to a recipient.

Circle API documentation: https://developers.circle.com/api-reference/circle-mint/payouts/create-payout.

func (*Client) PostRecipient

func (client *Client) PostRecipient(ctx context.Context, recipientRequest RecipientRequest) (*Recipient, error)

PostRecipient registers a new recipient in Circle's address book. This is needed in order to send a payout to that recipient.

Circle API documentation: https://developers.circle.com/api-reference/circle-mint/payouts/create-address-book-recipient.

func (*Client) PostTransfer

func (client *Client) PostTransfer(ctx context.Context, transferReq TransferRequest) (*Transfer, error)

PostTransfer creates a new transfer.

Circle API documentation: https://developers.circle.com/circle-mint/reference/createtransfer.

type ClientConfig

type ClientConfig struct {
	EncryptedAPIKey    *string   `db:"encrypted_api_key"`
	WalletID           *string   `db:"wallet_id"`
	EncrypterPublicKey *string   `db:"encrypter_public_key"`
	UpdatedAt          time.Time `db:"updated_at"`
	CreatedAt          time.Time `db:"created_at"`
}

type ClientConfigModel

type ClientConfigModel struct {
	DBConnectionPool db.DBConnectionPool
	Encrypter        utils.PrivateKeyEncrypter
}

func NewClientConfigModel

func NewClientConfigModel(dbConnectionPool db.DBConnectionPool) *ClientConfigModel

func (*ClientConfigModel) Get

Get retrieves the circle client config from the database if it exists.

func (*ClientConfigModel) GetDecryptedAPIKey

func (m *ClientConfigModel) GetDecryptedAPIKey(ctx context.Context, passphrase string) (string, error)

GetDecryptedAPIKey retrieves the decrypted API key from the database.

func (*ClientConfigModel) Upsert

func (m *ClientConfigModel) Upsert(ctx context.Context, configUpdate ClientConfigUpdate) error

Upsert insert or update the client configuration for Circle into the database.

type ClientConfigModelInterface

type ClientConfigModelInterface interface {
	Upsert(ctx context.Context, configUpdate ClientConfigUpdate) error
	GetDecryptedAPIKey(ctx context.Context, passphrase string) (string, error)
	Get(ctx context.Context) (*ClientConfig, error)
}

type ClientConfigUpdate

type ClientConfigUpdate struct {
	EncryptedAPIKey    *string `db:"encrypted_api_key"`
	WalletID           *string `db:"wallet_id"`
	EncrypterPublicKey *string `db:"encrypter_public_key"`
}

type ClientFactory

type ClientFactory func(opts ClientOptions) ClientInterface

ClientFactory is a function that creates a ClientInterface.

type ClientInterface

type ClientInterface interface {
	Ping(ctx context.Context) (bool, error)
	PostTransfer(ctx context.Context, transferRequest TransferRequest) (*Transfer, error) // TODO: remove this method in https://stellarorg.atlassian.net/browse/SDP-1448
	GetTransferByID(ctx context.Context, id string) (*Transfer, error)                    // TODO: remove this method in https://stellarorg.atlassian.net/browse/SDP-1448
	PostRecipient(ctx context.Context, recipientRequest RecipientRequest) (*Recipient, error)
	GetRecipientByID(ctx context.Context, id string) (*Recipient, error)
	PostPayout(ctx context.Context, payoutRequest PayoutRequest) (*Payout, error)
	GetPayoutByID(ctx context.Context, id string) (*Payout, error)
	GetBusinessBalances(ctx context.Context) (*Balances, error)
	GetAccountConfiguration(ctx context.Context) (*AccountConfiguration, error)
}

ClientInterface defines the interface for interacting with the Circle API.

func NewClient

func NewClient(opts ClientOptions) ClientInterface

NewClient creates a new instance of Circle Client.

type ClientOptions

type ClientOptions struct {
	NetworkType    utils.NetworkType
	APIKey         string
	TenantManager  tenant.ManagerInterface
	MonitorService monitor.MonitorServiceInterface
}

type ConfigurationResponse

type ConfigurationResponse struct {
	Data AccountConfiguration `json:"data,omitempty"`
}

ConfigurationResponse represents the response containing account configuration.

type Environment

type Environment string

Environment holds the possible environments for the Circle API.

const (
	Production Environment = "https://api.circle.com"
	Sandbox    Environment = "https://api-sandbox.circle.com"
)

type ListBusinessBalancesResponse

type ListBusinessBalancesResponse struct {
	Data Balances `json:"data,omitempty"`
}

ListBusinessBalancesResponse represents the response containing business balances.

type MockClient

type MockClient struct {
	mock.Mock
}

MockClient is an autogenerated mock type for the ClientInterface type

func NewMockClient

func NewMockClient(t interface {
	mock.TestingT
	Cleanup(func())
}) *MockClient

NewMockClient creates a new instance of MockClient. It also registers a testing interface on the mock and a cleanup function to assert the mocks expectations. The first argument is typically a *testing.T value.

func (*MockClient) GetAccountConfiguration

func (_m *MockClient) GetAccountConfiguration(ctx context.Context) (*AccountConfiguration, error)

GetAccountConfiguration provides a mock function with given fields: ctx

func (*MockClient) GetBusinessBalances

func (_m *MockClient) GetBusinessBalances(ctx context.Context) (*Balances, error)

GetBusinessBalances provides a mock function with given fields: ctx

func (*MockClient) GetPayoutByID

func (_m *MockClient) GetPayoutByID(ctx context.Context, id string) (*Payout, error)

GetPayoutByID provides a mock function with given fields: ctx, id

func (*MockClient) GetRecipientByID

func (_m *MockClient) GetRecipientByID(ctx context.Context, id string) (*Recipient, error)

GetRecipientByID provides a mock function with given fields: ctx, id

func (*MockClient) GetTransferByID

func (_m *MockClient) GetTransferByID(ctx context.Context, id string) (*Transfer, error)

GetTransferByID provides a mock function with given fields: ctx, id

func (*MockClient) Ping

func (_m *MockClient) Ping(ctx context.Context) (bool, error)

Ping provides a mock function with given fields: ctx

func (*MockClient) PostPayout

func (_m *MockClient) PostPayout(ctx context.Context, payoutRequest PayoutRequest) (*Payout, error)

PostPayout provides a mock function with given fields: ctx, payoutRequest

func (*MockClient) PostRecipient

func (_m *MockClient) PostRecipient(ctx context.Context, recipientRequest RecipientRequest) (*Recipient, error)

PostRecipient provides a mock function with given fields: ctx, recipientRequest

func (*MockClient) PostTransfer

func (_m *MockClient) PostTransfer(ctx context.Context, transferRequest TransferRequest) (*Transfer, error)

PostTransfer provides a mock function with given fields: ctx, transferRequest

type MockClientConfigModel

type MockClientConfigModel struct {
	mock.Mock
}

MockClientConfigModel is an autogenerated mock type for the ClientConfigModelInterface type

func NewMockClientConfigModel

func NewMockClientConfigModel(t interface {
	mock.TestingT
	Cleanup(func())
}) *MockClientConfigModel

NewMockClientConfigModel creates a new instance of MockClientConfigModel. It also registers a testing interface on the mock and a cleanup function to assert the mocks expectations. The first argument is typically a *testing.T value.

func (*MockClientConfigModel) Get

Get provides a mock function with given fields: ctx

func (*MockClientConfigModel) GetDecryptedAPIKey

func (_m *MockClientConfigModel) GetDecryptedAPIKey(ctx context.Context, passphrase string) (string, error)

GetDecryptedAPIKey provides a mock function with given fields: ctx, passphrase

func (*MockClientConfigModel) Upsert

func (_m *MockClientConfigModel) Upsert(ctx context.Context, configUpdate ClientConfigUpdate) error

Upsert provides a mock function with given fields: ctx, configUpdate

type MockService

type MockService struct {
	mock.Mock
}

MockService is an autogenerated mock type for the ServiceInterface type

func NewMockService

func NewMockService(t interface {
	mock.TestingT
	Cleanup(func())
}) *MockService

NewMockService creates a new instance of MockService. It also registers a testing interface on the mock and a cleanup function to assert the mocks expectations. The first argument is typically a *testing.T value.

func (*MockService) GetAccountConfiguration

func (_m *MockService) GetAccountConfiguration(ctx context.Context) (*AccountConfiguration, error)

GetAccountConfiguration provides a mock function with given fields: ctx

func (*MockService) GetBusinessBalances

func (_m *MockService) GetBusinessBalances(ctx context.Context) (*Balances, error)

GetBusinessBalances provides a mock function with given fields: ctx

func (*MockService) GetPayoutByID

func (_m *MockService) GetPayoutByID(ctx context.Context, id string) (*Payout, error)

GetPayoutByID provides a mock function with given fields: ctx, id

func (*MockService) GetRecipientByID

func (_m *MockService) GetRecipientByID(ctx context.Context, id string) (*Recipient, error)

GetRecipientByID provides a mock function with given fields: ctx, id

func (*MockService) GetTransferByID

func (_m *MockService) GetTransferByID(ctx context.Context, id string) (*Transfer, error)

GetTransferByID provides a mock function with given fields: ctx, id

func (*MockService) Ping

func (_m *MockService) Ping(ctx context.Context) (bool, error)

Ping provides a mock function with given fields: ctx

func (*MockService) PostPayout

func (_m *MockService) PostPayout(ctx context.Context, payoutRequest PayoutRequest) (*Payout, error)

PostPayout provides a mock function with given fields: ctx, payoutRequest

func (*MockService) PostRecipient

func (_m *MockService) PostRecipient(ctx context.Context, recipientRequest RecipientRequest) (*Recipient, error)

PostRecipient provides a mock function with given fields: ctx, recipientRequest

func (*MockService) PostTransfer

func (_m *MockService) PostTransfer(ctx context.Context, transferRequest TransferRequest) (*Transfer, error)

PostTransfer provides a mock function with given fields: ctx, transferRequest

func (*MockService) SendPayout

func (_m *MockService) SendPayout(ctx context.Context, paymentRequest PaymentRequest) (*Payout, error)

SendPayout provides a mock function with given fields: ctx, paymentRequest

func (*MockService) SendTransfer

func (_m *MockService) SendTransfer(ctx context.Context, paymentRequest PaymentRequest) (*Transfer, error)

SendTransfer provides a mock function with given fields: ctx, paymentRequest

type PaymentRequest

type PaymentRequest struct {
	SourceWalletID            string
	RecipientID               string
	DestinationStellarAddress string
	DestinationStellarMemo    string
	APIType                   APIType
	Amount                    string
	StellarAssetCode          string
	IdempotencyKey            string
}

func (PaymentRequest) GetCircleAssetCode

func (p PaymentRequest) GetCircleAssetCode() (string, error)

GetCircleAssetCode converts the request's Stellar asset code to a Circle's asset code.

func (PaymentRequest) Validate

func (p PaymentRequest) Validate() error

type Payout

type Payout struct {
	ID              string            `json:"id"`
	Destination     TransferAccount   `json:"destination"`
	Amount          Balance           `json:"amount"`
	ToAmount        Balance           `json:"toAmount"`
	TransactionHash string            `json:"externalRef,omitempty"`
	CreateDate      time.Time         `json:"createDate"`
	UpdateDate      time.Time         `json:"updateDate"`
	SourceWalletID  string            `json:"sourceWalletId"`
	Fees            Balance           `json:"fees,omitempty"`
	Status          TransferStatus    `json:"status"`
	ErrorCode       TransferErrorCode `json:"errorCode,omitempty"`
	RiskEvaluation  RiskEvaluation    `json:"riskEvaluation,omitempty"`
}

type PayoutRequest

type PayoutRequest struct {
	IdempotencyKey string          `json:"idempotencyKey"`
	Source         TransferAccount `json:"source"`
	Destination    TransferAccount `json:"destination"`
	Amount         Balance         `json:"amount"`
	ToAmount       ToAmount        `json:"toAmount"`
}

PayoutRequest represents the request to create a new transfer.

type PayoutResponse

type PayoutResponse struct {
	Data Payout `json:"data"`
}

PayoutResponse represents the response from the Circle APIs.

type Recipient

type Recipient struct {
	ID         string            `json:"id"`
	Chain      string            `json:"chain"`
	AddressTag string            `json:"addressTag"`
	Address    string            `json:"address"`
	Metadata   RecipientMetadata `json:"metadata"`
	Status     string            `json:"status"`
	CreateDate string            `json:"createDate"`
	UpdateDate string            `json:"updateDate"`
}

type RecipientMetadata

type RecipientMetadata struct {
	Nickname string `json:"nickname"`
	Email    string `json:"email"`
	// BNS stands for Blockchain Name Service (e.g. ENS) domain for the address.
	BNS string `json:"bns"`
}

type RecipientRequest

type RecipientRequest struct {
	IdempotencyKey string            `json:"idempotencyKey"`
	Address        string            `json:"address"`
	AddressTag     string            `json:"addressTag"`
	Chain          string            `json:"chain"`
	Metadata       RecipientMetadata `json:"metadata"`
}

type RecipientResponse

type RecipientResponse struct {
	Data Recipient `json:"data"`
}

RecipientResponse represents the response from the Circle APIs.

type RetryableError

type RetryableError struct {
	// contains filtered or unexported fields
}

func (RetryableError) Error

func (re RetryableError) Error() string

type RiskEvaluation

type RiskEvaluation struct {
	Decision string `json:"decision"`
	Reason   string `json:"reason"`
}

type Service

type Service struct {
	ClientFactory        ClientFactory
	ClientConfigModel    ClientConfigModelInterface
	NetworkType          utils.NetworkType
	EncryptionPassphrase string
	TenantManager        tenant.ManagerInterface
	MonitorService       monitor.MonitorServiceInterface
}

func NewService

func NewService(opts ServiceOptions) (*Service, error)

func (*Service) GetAccountConfiguration

func (s *Service) GetAccountConfiguration(ctx context.Context) (*AccountConfiguration, error)

func (*Service) GetBusinessBalances

func (s *Service) GetBusinessBalances(ctx context.Context) (*Balances, error)

func (*Service) GetPayoutByID

func (s *Service) GetPayoutByID(ctx context.Context, payoutID string) (*Payout, error)

func (*Service) GetRecipientByID

func (s *Service) GetRecipientByID(ctx context.Context, recipientID string) (*Recipient, error)

func (*Service) GetTransferByID

func (s *Service) GetTransferByID(ctx context.Context, transferID string) (*Transfer, error)

func (*Service) Ping

func (s *Service) Ping(ctx context.Context) (bool, error)

func (*Service) PostPayout

func (s *Service) PostPayout(ctx context.Context, payoutRequest PayoutRequest) (*Payout, error)

func (*Service) PostRecipient

func (s *Service) PostRecipient(ctx context.Context, recipientRequest RecipientRequest) (*Recipient, error)

func (*Service) PostTransfer

func (s *Service) PostTransfer(ctx context.Context, transferRequest TransferRequest) (*Transfer, error)

func (*Service) SendPayout

func (s *Service) SendPayout(ctx context.Context, paymentRequest PaymentRequest) (*Payout, error)

func (*Service) SendTransfer

func (s *Service) SendTransfer(ctx context.Context, paymentRequest PaymentRequest) (*Transfer, error)

type ServiceInterface

type ServiceInterface interface {
	ClientInterface
	SendPayout(ctx context.Context, paymentRequest PaymentRequest) (*Payout, error)
	SendTransfer(ctx context.Context, paymentRequest PaymentRequest) (*Transfer, error)
}

ServiceInterface defines the interface for Circle related SDP operations.

type ServiceOptions

type ServiceOptions struct {
	ClientFactory        ClientFactory
	ClientConfigModel    ClientConfigModelInterface
	TenantManager        tenant.ManagerInterface
	NetworkType          utils.NetworkType
	EncryptionPassphrase string
	MonitorService       monitor.MonitorServiceInterface
}

func (ServiceOptions) Validate

func (o ServiceOptions) Validate() error

type ToAmount

type ToAmount struct {
	Currency string `json:"currency"`
}

type Transfer

type Transfer struct {
	ID              string            `json:"id"`
	Source          TransferAccount   `json:"source"`
	Destination     TransferAccount   `json:"destination"`
	Amount          Balance           `json:"amount"`
	TransactionHash string            `json:"transactionHash,omitempty"`
	Status          TransferStatus    `json:"status"`
	ErrorCode       TransferErrorCode `json:"errorCode,omitempty"`
	CreateDate      time.Time         `json:"createDate"`
}

Transfer represents a transfer of funds from a Circle Endpoint to another. A circle endpoint can be a wallet, card, wire, or blockchain address.

type TransferAccount

type TransferAccount struct {
	Type       TransferAccountType `json:"type"`
	ID         string              `json:"id,omitempty"`
	Chain      string              `json:"chain,omitempty"`
	Address    string              `json:"address,omitempty"`
	AddressTag string              `json:"addressTag,omitempty"`
}

TransferAccount represents the source or destination of the transfer.

type TransferAccountType

type TransferAccountType string

TransferAccountType represents the type of the source or destination of the transfer.

const (
	TransferAccountTypeCard        TransferAccountType = "card"
	TransferAccountTypeWire        TransferAccountType = "wire"
	TransferAccountTypeBlockchain  TransferAccountType = "blockchain"
	TransferAccountTypeAddressBook TransferAccountType = "address_book"
	TransferAccountTypeWallet      TransferAccountType = "wallet"
)

type TransferErrorCode

type TransferErrorCode string
const (
	TransferErrorCodeInsufficientFunds TransferErrorCode = "insufficient_funds"
	TransferErrorCodeBlockchainError   TransferErrorCode = "blockchain_error"
	TransferErrorCodeTransferDenied    TransferErrorCode = "transfer_denied"
	TransferErrorCodeTransferFailed    TransferErrorCode = "transfer_failed"
)

type TransferRequest

type TransferRequest struct {
	Source         TransferAccount `json:"source"`
	Destination    TransferAccount `json:"destination"`
	Amount         Balance         `json:"amount"`
	IdempotencyKey string          `json:"idempotencyKey"`
}

TransferRequest represents the request to create a new transfer.

type TransferResponse

type TransferResponse struct {
	Data Transfer `json:"data"`
}

TransferResponse represents the response from the Circle APIs.

type TransferStatus

type TransferStatus string
const (
	TransferStatusPending  TransferStatus = "pending"
	TransferStatusComplete TransferStatus = "complete" // means success
	TransferStatusFailed   TransferStatus = "failed"
)

func (TransferStatus) ToPaymentStatus

func (s TransferStatus) ToPaymentStatus() (data.PaymentStatus, error)

type WalletConfig

type WalletConfig struct {
	MasterWalletID string `json:"masterWalletId,omitempty"`
}

WalletConfig represents the wallet configuration with details such as the master wallet ID.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL