agora.client package

Subpackages

• agora.client.account package
  • Submodules
  • agora.client.account.resolution module
  • Module contents

Submodules

agora.client.client module

class agora.client.client.BaseClient

Bases: object

An interface for accessing Agora features.

close()

Closes the connection-related resources (e.g. the gRPC channel) used by the client. Subsequent requests to this client will cause an exception to be thrown.

Return type:

None

create_account(private_key, commitment=None, subsidizer=None)

Creates a new Kin account.

Parameters:

• private_key (PrivateKey) – The PrivateKey of the account to create

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the create account transaction. The subsidizer will be used both as the payer of the transaction and will also be given the CloseAccount authority on the created account.

Raise:

UnsupportedVersionError

Raise:

AccountExistsError

get_balance(public_key, commitment=None, account_resolution=<AccountResolution.PREFERRED: 1>)

Retrieves the balance of an account.

Parameters:

• public_key (PublicKey) – The PublicKey of the account to retrieve the balance for.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• account_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use if the original account was not found. Only applies for Kin 4. Defaults to AccountResolution.PREFERRED.

Raise:

UnsupportedVersionError

Raise:

AccountNotFoundError

Return type:

int

Returns:

The balance of the account, in quarks.

get_transaction(tx_id, commitment=None)

Retrieves a transaction.

Parameters:

• tx_id (bytes) – The id of the transaction to retrieve. This can be either the 32-byte hash of a Stellar-based transaction (on Kin 2 or 3) or the 64-byte signature of a Solana-based transaction (on Kin 4).

• commitment (Optional[Commitment]) – (optional) The commitment to use.

Return type:

TransactionData

Returns:

a TransactionData object.

merge_token_accounts(private_key, create_associated_account, commitment=None, subsidizer=None)

Merges all of an account’s token accounts into one.

Parameters:

• private_key (PrivateKey) – The owner account for which to merge token accounts.

• create_associated_account (bool) – Indicates whether or not to create the associated token account and use it as the destination for all the merged token accounts.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the merge account transaction. The subsidizer will be used both as the payer of the transaction and will also be given the CloseAccount authority on the created account.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

Return type:

Optional[bytes]

Returns:

The id of the transaction, if one was submitted. If None gets returned, there was no transaction submitted.

request_airdrop(public_key, quarks, commitment=None)

Requests an airdrop of Kin to a Kin account. Only available on Kin 4 on the test environment.

Parameters:

• public_key (PublicKey) – the public key of the Kin token account to airdrop to. To get all the token accounts owned by an owner, use Client.resolve_token_accounts.

• quarks (int) – The amount, in quarks, to request.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

Raise:

UnsupportedMethodError

Return type:

bytes

Returns:

The transaction ID of the airdrop transaction submitted by Agora.

resolve_token_accounts(public_key)

Resolves the token accounts owned by the specified account on Kin 4.

Parameters:

public_key (PublicKey) – The public key of the owner account.

Return type:

List[PublicKey]

Returns:

a List of token accounts owned by the account with the provided public key.

submit_earn_batch(batch, commitment=None, sender_resolution=<AccountResolution.PREFERRED: 1>, dest_resolution=<AccountResolution.PREFERRED: 1>)

Submit multiple earn payments.

Parameters:

• batch (EarnBatch) – The EarnBatch to submit. The number of earns in the batch is limited to 15, which is roughly the max number of transfers that can fit inside a Solana transaction.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• sender_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the sender account if the transaction fails due to an account error. Only applies for Kin 4 transactions. Defaults to AccountResolution.PREFERRED.

• dest_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the earn destination accounts if the transaction fails due to an account error. Only applies for Kin 4 transactions. Defaults to AccountResolution.PREFERRED.

Raise:

UnsupportedVersionError

Return type:

EarnBatchResult

Returns:

a BatchEarnResult

submit_payment(payment, commitment=None, sender_resolution=<AccountResolution.PREFERRED: 1>, dest_resolution=<AccountResolution.PREFERRED: 1>, sender_create=False)

Submits a payment to the Kin blockchain.

Parameters:

• payment (Payment) – The Payment to submit.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• sender_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the payment sender account if the transaction fails due to an account error. Defaults to AccountResolution.PREFERRED.

• dest_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the payment destination account if the transaction fails due to an account error. Defaults to AccountResolution.PREFERRED.

• sender_create (Optional[bool]) – (optional) Specifies whether or not destination token accounts should be created if they do not exist.

Raise:

UnsupportedVersionError

Raise:

InvalidSignatureError

Raise:

InsufficientBalanceError

Raise:

BadNonceError

Raise:

TransactionError

Raise:

InvoiceError

Return type:

bytes

Returns:

The id of the transaction.

class agora.client.client.Client(env, app_index=0, grpc_channel=None, endpoint=None, retry_config=None, default_commitment=<Commitment.SINGLE: 1>)

Bases: agora.client.client.BaseClient

A Client object for accessing Agora API features.

Parameters:

• env (Environment) – The Environment to use.

• app_index (int) – (optional) The Agora index of the app, used for all transactions and requests. Required to make use of invoices.

• grpc_channel (Optional[Channel]) – (optional) A GRPC Channel object to use for Agora requests. Only one of grpc_channel or endpoint should be set.

• endpoint (Optional[str]) – (optional) An endpoint to use instead of the default Agora endpoints. Only one of grpc_channel or endpoint should be set.

• retry_config (Optional[RetryConfig]) – (optional): A RetryConfig object to configure Agora retries. If not provided, a default configuration will be used.

• default_commitment (Optional[Commitment]) – (optional) The commitment requirement to use by default for Kin 4 Agora requests. Defaults to using Commitment.SINGLE.

close()

Closes the connection-related resources (e.g. the gRPC channel) used by the client. Subsequent requests to this client will cause an exception to be thrown.

Return type:

None

create_account(private_key, commitment=None, subsidizer=None)

Creates a new Kin account.

Parameters:

• private_key (PrivateKey) – The PrivateKey of the account to create

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the create account transaction. The subsidizer will be used both as the payer of the transaction and will also be given the CloseAccount authority on the created account.

Raise:

UnsupportedVersionError

Raise:

AccountExistsError

get_balance(public_key, commitment=None, account_resolution=<AccountResolution.PREFERRED: 1>)

Retrieves the balance of an account.

Parameters:

• public_key (PublicKey) – The PublicKey of the account to retrieve the balance for.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• account_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use if the original account was not found. Only applies for Kin 4. Defaults to AccountResolution.PREFERRED.

Raise:

UnsupportedVersionError

Raise:

AccountNotFoundError

Return type:

int

Returns:

The balance of the account, in quarks.

get_transaction(tx_id, commitment=None)

Retrieves a transaction.

Parameters:

• tx_id (bytes) – The id of the transaction to retrieve. This can be either the 32-byte hash of a Stellar-based transaction (on Kin 2 or 3) or the 64-byte signature of a Solana-based transaction (on Kin 4).

• commitment (Optional[Commitment]) – (optional) The commitment to use.

Return type:

TransactionData

Returns:

a TransactionData object.

merge_token_accounts(private_key, create_associated_account, commitment=None, subsidizer=None)

Merges all of an account’s token accounts into one.

Parameters:

• private_key (PrivateKey) – The owner account for which to merge token accounts.

• create_associated_account (bool) – Indicates whether or not to create the associated token account and use it as the destination for all the merged token accounts.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the merge account transaction. The subsidizer will be used both as the payer of the transaction and will also be given the CloseAccount authority on the created account.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

Return type:

Optional[bytes]

Returns:

The id of the transaction, if one was submitted. If None gets returned, there was no transaction submitted.

request_airdrop(public_key, quarks, commitment=None)

Requests an airdrop of Kin to a Kin account. Only available on Kin 4 on the test environment.

Parameters:

• public_key (PublicKey) – the public key of the Kin token account to airdrop to. To get all the token accounts owned by an owner, use Client.resolve_token_accounts.

• quarks (int) – The amount, in quarks, to request.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

Raise:

UnsupportedMethodError

Return type:

bytes

Returns:

The transaction ID of the airdrop transaction submitted by Agora.

resolve_token_accounts(public_key)

Resolves the token accounts owned by the specified account on Kin 4.

Parameters:

public_key (PublicKey) – The public key of the owner account.

Return type:

List[PublicKey]

Returns:

a List of token accounts owned by the account with the provided public key.

submit_earn_batch(batch, commitment=None, sender_resolution=<AccountResolution.PREFERRED: 1>, dest_resolution=<AccountResolution.PREFERRED: 1>)

Submit multiple earn payments.

Parameters:

• batch (EarnBatch) – The EarnBatch to submit. The number of earns in the batch is limited to 15, which is roughly the max number of transfers that can fit inside a Solana transaction.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• sender_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the sender account if the transaction fails due to an account error. Only applies for Kin 4 transactions. Defaults to AccountResolution.PREFERRED.

• dest_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the earn destination accounts if the transaction fails due to an account error. Only applies for Kin 4 transactions. Defaults to AccountResolution.PREFERRED.

Raise:

UnsupportedVersionError

Return type:

EarnBatchResult

Returns:

a BatchEarnResult

submit_payment(payment, commitment=None, sender_resolution=<AccountResolution.PREFERRED: 1>, dest_resolution=<AccountResolution.PREFERRED: 1>, sender_create=False)

Submits a payment to the Kin blockchain.

Parameters:

• payment (Payment) – The Payment to submit.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• sender_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the payment sender account if the transaction fails due to an account error. Defaults to AccountResolution.PREFERRED.

• dest_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the payment destination account if the transaction fails due to an account error. Defaults to AccountResolution.PREFERRED.

• sender_create (Optional[bool]) – (optional) Specifies whether or not destination token accounts should be created if they do not exist.

Raise:

UnsupportedVersionError

Raise:

InvalidSignatureError

Raise:

InsufficientBalanceError

Raise:

BadNonceError

Raise:

TransactionError

Raise:

InvoiceError

Return type:

bytes

Returns:

The id of the transaction.

class agora.client.client.RetryConfig(max_retries=None, min_delay=None, max_delay=None, max_nonce_refreshes=None)

Bases: object

A RetryConfig for configuring retries for Agora requests.

Parameters:

• max_retries (Optional[int]) – (optional) The max number of times the client will retry a request, excluding the initial attempt. Defaults to 5 if value is not provided or value is below 0.

• max_nonce_refreshes (Optional[int]) – (optional) The max number of times the client will attempt to refresh a nonce, excluding the initial attempt. Defaults to 3 if value is not provided or value is below 0.

• min_delay (Optional[float]) – (optional) The minimum amount of time to delay between request retries, in seconds. Defaults to 0.5 seconds if value is not provided or value is below 0.

• min_delay – (optional) The maximum amount of time to delay between request retries, in seconds. Defaults to 5 seconds if value is not provided or value is below 0.

agora.client.environment module

class agora.client.environment.Environment(value)

Bases: enum.Enum

An Agora Environment.

PRODUCTION = 1

TEST = 2

agora.client.internal module

class agora.client.internal.InternalClient(grpc_channel, retry_strategies, app_index=0)

Bases: object

A low level client used for interacting with Agora APIs directly. The API for this client is _not_ stable and is not intended for general use. It is only exposed in case there needs to be low level access to Agora (beyond the gRPC directly). However, there is no stability guarantees between releases, or during a migration event.

create_solana_account(tx, commitment=<Commitment.SINGLE: 1>)

Submit a request to Agora to create a Solana account.

Parameters:

• tx (Transaction) – The Solana transaction to create an account.

• commitment (Optional[Commitment]) – The Commitment to use.

get_blockchain_version()

Get the blockchain version to use.

Return type:

int

Returns:

the blockchain version

get_minimum_balance_for_rent_exception()

Return type:

int

get_recent_blockhash()

Return type:

GetRecentBlockhashResponse

get_service_config()

Return type:

GetServiceConfigResponse

get_solana_account_info(public_key, commitment=<Commitment.SINGLE: 1>)

Get the info of a Solana account from Agora.

Parameters:

• public_key (PublicKey) – The PublicKey of the account to request the info for.

• commitment (Optional[Commitment]) – The Commitment to use.

Return type:

AccountInfo

Returns:

A AccountInfo object.

get_transaction(tx_id, commitment=<Commitment.SINGLE: 1>)

Get a transaction from Agora.

Parameters:

• tx_id (bytes) – The id of the transaction, in bytes.

• commitment (Optional[Commitment]) – The Commitment to use. Only applicable for Solana transactions.

Return type:

TransactionData

Returns:

A TransactionData object.

request_airdrop(public_key, quarks, commitment=<Commitment.SINGLE: 1>)

Return type:

bytes

resolve_token_accounts(public_key, include_account_info)

Resolves token accounts using Agora.

Parameters:

• public_key (PublicKey) – the public key of the account to resolve token accounts for.

• include_account_info (bool) – indicates whether to include token account info in the response

Return type:

List[AccountInfo]

Returns:

A list of AccountInfo objects each representing a token account. Information other than AccountInfo.account_id will only be populated if include_account_info is True.

sign_transaction(tx, invoice_list=None)

Submits a transaction

Parameters:

• tx (Transaction) –

• invoice_list (Optional[InvoiceList]) –

Return type:

SignTransactionResult

Returns:

A SignTransactionResult object.

submit_solana_transaction(tx, invoice_list=None, commitment=<Commitment.SINGLE: 1>, dedupe_id=None)

Submit a Solana transaction to Agora.

Parameters:

• tx (Transaction) – The Solana transaction.

• invoice_list (Optional[InvoiceList]) – (optional) An InvoiceList to associate with the transaction

• commitment (Optional[Commitment]) – The Commitment to use.

• dedupe_id (Optional[bytes]) – The dedupe ID to use for the transaction submission

Return type:

SubmitTransactionResult

Returns:

A SubmitTransactionResult object.

class agora.client.internal.SignTransactionResult(tx_id=None, invoice_errors=None)

Bases: object

class agora.client.internal.SubmitTransactionResult(tx_id=None, invoice_errors=None, errors=None)

Bases: object

Module contents

class agora.client.Client(env, app_index=0, grpc_channel=None, endpoint=None, retry_config=None, default_commitment=<Commitment.SINGLE: 1>)

Bases: agora.client.client.BaseClient

A Client object for accessing Agora API features.

Parameters:

• env (Environment) – The Environment to use.

• app_index (int) – (optional) The Agora index of the app, used for all transactions and requests. Required to make use of invoices.

• grpc_channel (Optional[Channel]) – (optional) A GRPC Channel object to use for Agora requests. Only one of grpc_channel or endpoint should be set.

• endpoint (Optional[str]) – (optional) An endpoint to use instead of the default Agora endpoints. Only one of grpc_channel or endpoint should be set.

• retry_config (Optional[RetryConfig]) – (optional): A RetryConfig object to configure Agora retries. If not provided, a default configuration will be used.

• default_commitment (Optional[Commitment]) – (optional) The commitment requirement to use by default for Kin 4 Agora requests. Defaults to using Commitment.SINGLE.

close()

Closes the connection-related resources (e.g. the gRPC channel) used by the client. Subsequent requests to this client will cause an exception to be thrown.

Return type:

None

create_account(private_key, commitment=None, subsidizer=None)

Creates a new Kin account.

Parameters:

• private_key (PrivateKey) – The PrivateKey of the account to create

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the create account transaction. The subsidizer will be used both as the payer of the transaction and will also be given the CloseAccount authority on the created account.

Raise:

UnsupportedVersionError

Raise:

AccountExistsError

get_balance(public_key, commitment=None, account_resolution=<AccountResolution.PREFERRED: 1>)

Retrieves the balance of an account.

Parameters:

• public_key (PublicKey) – The PublicKey of the account to retrieve the balance for.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• account_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use if the original account was not found. Only applies for Kin 4. Defaults to AccountResolution.PREFERRED.

Raise:

UnsupportedVersionError

Raise:

AccountNotFoundError

Return type:

int

Returns:

The balance of the account, in quarks.

get_transaction(tx_id, commitment=None)

Retrieves a transaction.

Parameters:

• tx_id (bytes) – The id of the transaction to retrieve. This can be either the 32-byte hash of a Stellar-based transaction (on Kin 2 or 3) or the 64-byte signature of a Solana-based transaction (on Kin 4).

• commitment (Optional[Commitment]) – (optional) The commitment to use.

Return type:

TransactionData

Returns:

a TransactionData object.

merge_token_accounts(private_key, create_associated_account, commitment=None, subsidizer=None)

Merges all of an account’s token accounts into one.

Parameters:

• private_key (PrivateKey) – The owner account for which to merge token accounts.

• create_associated_account (bool) – Indicates whether or not to create the associated token account and use it as the destination for all the merged token accounts.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the merge account transaction. The subsidizer will be used both as the payer of the transaction and will also be given the CloseAccount authority on the created account.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

Return type:

Optional[bytes]

Returns:

The id of the transaction, if one was submitted. If None gets returned, there was no transaction submitted.

request_airdrop(public_key, quarks, commitment=None)

Requests an airdrop of Kin to a Kin account. Only available on Kin 4 on the test environment.

Parameters:

• public_key (PublicKey) – the public key of the Kin token account to airdrop to. To get all the token accounts owned by an owner, use Client.resolve_token_accounts.

• quarks (int) – The amount, in quarks, to request.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

Raise:

UnsupportedMethodError

Return type:

bytes

Returns:

The transaction ID of the airdrop transaction submitted by Agora.

resolve_token_accounts(public_key)

Resolves the token accounts owned by the specified account on Kin 4.

Parameters:

public_key (PublicKey) – The public key of the owner account.

Return type:

List[PublicKey]

Returns:

a List of token accounts owned by the account with the provided public key.

submit_earn_batch(batch, commitment=None, sender_resolution=<AccountResolution.PREFERRED: 1>, dest_resolution=<AccountResolution.PREFERRED: 1>)

Submit multiple earn payments.

Parameters:

• batch (EarnBatch) – The EarnBatch to submit. The number of earns in the batch is limited to 15, which is roughly the max number of transfers that can fit inside a Solana transaction.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• sender_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the sender account if the transaction fails due to an account error. Only applies for Kin 4 transactions. Defaults to AccountResolution.PREFERRED.

• dest_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the earn destination accounts if the transaction fails due to an account error. Only applies for Kin 4 transactions. Defaults to AccountResolution.PREFERRED.

Raise:

UnsupportedVersionError

Return type:

EarnBatchResult

Returns:

a BatchEarnResult

submit_payment(payment, commitment=None, sender_resolution=<AccountResolution.PREFERRED: 1>, dest_resolution=<AccountResolution.PREFERRED: 1>, sender_create=False)

Submits a payment to the Kin blockchain.

Parameters:

• payment (Payment) – The Payment to submit.

• commitment (Optional[Commitment]) – (optional) The commitment to use.

• sender_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the payment sender account if the transaction fails due to an account error. Defaults to AccountResolution.PREFERRED.

• dest_resolution (Optional[AccountResolution]) – (optional) The AccountResolution to use for the payment destination account if the transaction fails due to an account error. Defaults to AccountResolution.PREFERRED.

• sender_create (Optional[bool]) – (optional) Specifies whether or not destination token accounts should be created if they do not exist.

Raise:

UnsupportedVersionError

Raise:

InvalidSignatureError

Raise:

InsufficientBalanceError

Raise:

BadNonceError

Raise:

TransactionError

Raise:

InvoiceError

Return type:

bytes

Returns:

The id of the transaction.

class agora.client.Environment(value)

Bases: enum.Enum

An Agora Environment.

PRODUCTION = 1

TEST = 2

class agora.client.RetryConfig(max_retries=None, min_delay=None, max_delay=None, max_nonce_refreshes=None)

Bases: object

A RetryConfig for configuring retries for Agora requests.

Parameters:

• max_retries (Optional[int]) – (optional) The max number of times the client will retry a request, excluding the initial attempt. Defaults to 5 if value is not provided or value is below 0.

• max_nonce_refreshes (Optional[int]) – (optional) The max number of times the client will attempt to refresh a nonce, excluding the initial attempt. Defaults to 3 if value is not provided or value is below 0.

• min_delay (Optional[float]) – (optional) The minimum amount of time to delay between request retries, in seconds. Defaults to 0.5 seconds if value is not provided or value is below 0.

• min_delay – (optional) The maximum amount of time to delay between request retries, in seconds. Defaults to 5 seconds if value is not provided or value is below 0.