Class: MixinBot::API

Inherits:
Object
  • Object
show all
Includes:
Address, App, Asset, Attachment, Auth, Blaze, Chain, Code, ComputerApi, Conversation, Deposit, EncryptedMessage, Fiat, Inscription, LegacyCollectible, LegacyMultisig, LegacyOutput, LegacyPayment, LegacySnapshot, LegacyTransaction, LegacyTransfer, LegacyUser, Me, Message, Multisig, Network, NetworkAsset, Output, Payment, Pin, PinPayload, Rpc, Session, Snapshot, Tip, Transaction, Transfer, Turn, User, Withdraw
Defined in:
lib/mixin_bot/api.rb,
lib/mixin_bot/api/me.rb,
lib/mixin_bot/api/app.rb,
lib/mixin_bot/api/pin.rb,
lib/mixin_bot/api/rpc.rb,
lib/mixin_bot/api/tip.rb,
lib/mixin_bot/api/auth.rb,
lib/mixin_bot/api/code.rb,
lib/mixin_bot/api/fiat.rb,
lib/mixin_bot/api/turn.rb,
lib/mixin_bot/api/user.rb,
lib/mixin_bot/api/asset.rb,
lib/mixin_bot/api/blaze.rb,
lib/mixin_bot/api/chain.rb,
lib/mixin_bot/api/output.rb,
lib/mixin_bot/api/address.rb,
lib/mixin_bot/api/deposit.rb,
lib/mixin_bot/api/message.rb,
lib/mixin_bot/api/network.rb,
lib/mixin_bot/api/payment.rb,
lib/mixin_bot/api/session.rb,
lib/mixin_bot/api/multisig.rb,
lib/mixin_bot/api/snapshot.rb,
lib/mixin_bot/api/transfer.rb,
lib/mixin_bot/api/withdraw.rb,
lib/mixin_bot/api/attachment.rb,
lib/mixin_bot/api/inscription.rb,
lib/mixin_bot/api/legacy_user.rb,
lib/mixin_bot/api/pin_payload.rb,
lib/mixin_bot/api/transaction.rb,
lib/mixin_bot/api/computer_api.rb,
lib/mixin_bot/api/conversation.rb,
lib/mixin_bot/api/legacy_output.rb,
lib/mixin_bot/api/network_asset.rb,
lib/mixin_bot/api/legacy_payment.rb,
lib/mixin_bot/api/legacy_multisig.rb,
lib/mixin_bot/api/legacy_snapshot.rb,
lib/mixin_bot/api/legacy_transfer.rb,
lib/mixin_bot/api/encrypted_message.rb,
lib/mixin_bot/api/legacy_collectible.rb,
lib/mixin_bot/api/legacy_transaction.rb

Overview

Main API interface for interacting with Mixin Network.

The API class provides access to all Mixin Network endpoints including:

  • User and bot profile management

  • Asset management (read assets, check balances)

  • Transfers and payments (Safe API and legacy)

  • Messaging (send/receive messages via Blaze)

  • Conversations and encrypted messages

  • Multisig operations

  • NFT and collectible operations

  • Transaction building and signing

  • Withdrawal operations

Usage

Using Global Configuration

MixinBot.configure do
  self.app_id = 'your-app-id'
  self.session_id = 'your-session-id'
  self.session_private_key = 'your-private-key'
  self.server_public_key = 'server-public-key'
end

# Access via global instance
MixinBot.api.me
MixinBot.api.assets

Creating Dedicated Instances

api = MixinBot::API.new(
  app_id: 'your-app-id',
  session_id: 'your-session-id',
  session_private_key: 'your-private-key',
  server_public_key: 'server-public-key'
)

api.me
api.assets

API Categories

Profile & Users

  • me, safe_me, update_me - Bot profile operations

  • read_user, read_users, search_user - User lookup

  • friends - List bot friends

Assets & Balance

  • assets, asset - Read asset information

  • ticker - Get asset ticker data

  • safe_assets - Read Safe API assets

Transfers & Payments

  • create_transfer, create_safe_transfer - Send payments

  • build_safe_transaction - Build raw transactions

  • sign_safe_transaction - Sign transactions

  • send_safe_transaction - Submit signed transactions

Messaging

  • start_blaze_connect - Connect to Blaze WebSocket

  • send_message - Send text/data messages

  • send_encrypted_messages - Send encrypted messages

Multisig & UTXOs

  • safe_outputs - Read unspent outputs

  • multisig_payments - Multisig payment operations

  • safe_ghost_keys - Generate ghost keys

NFT & Collectibles

  • create_collectible_request - Create NFT requests

  • read_collectibles - Read collectible tokens

  • inscriptions - Inscription operations

Examples

Get bot information:

profile = MixinBot.api.me
puts profile['full_name']

Read assets:

assets = MixinBot.api.assets
assets.each do |asset|
  puts "#{asset['symbol']}: #{asset['balance']}"
end

Send a transfer:

result = MixinBot.api.create_transfer(
  members: ['recipient-user-id'],
  threshold: 1,
  asset_id: 'asset-uuid',
  amount: '0.01',
  memo: 'Payment for services',
  trace_id: SecureRandom.uuid
)

Defined Under Namespace

Modules: Address, App, Asset, Attachment, Auth, Blaze, Chain, Code, ComputerApi, Conversation, Deposit, EncryptedMessage, Fiat, Inscription, LegacyCollectible, LegacyMultisig, LegacyOutput, LegacyPayment, LegacySnapshot, LegacyTransaction, LegacyTransfer, LegacyUser, Me, Message, Multisig, Network, NetworkAsset, Output, Payment, Pin, PinPayload, Rpc, Session, Snapshot, Tip, Transaction, Transfer, Turn, User, Withdraw

Constant Summary collapse

COLLECTIBLE_TRANSACTION_ARGUMENTS =

collectible = 

type: 'non_fungible_output',
user_id: '',
output_id: '',
token_id: '',
transaction_hash: '',
output_index: '',
amount: 1,
senders: [],
sender_threshold: 1,
receivers: [],
receivers_threshold: 1,
state: 'unspent'


%i[collectible nfo receivers receivers_threshold].freeze

Constants included from User

User::SAFE_REGISTER_MAX_RETRIES, User::SAFE_REGISTER_RETRY_BASE_DELAY, User::TIP_PIN_PROPAGATION_DELAY

Constants included from Transaction

Transaction::EXTRA_SIZE_STORAGE_CAPACITY, Transaction::EXTRA_STORAGE_PRICE_STEP, Transaction::INSCRIBE_TRANSACTION_ARGUMENTS, Transaction::OCCUPY_INSCRIPTION_TRANSACTION_ARGUMENTS, Transaction::OUTPUT_TYPE_SCRIPT, Transaction::OUTPUT_TYPE_WITHDRAW_SUBMIT, Transaction::SAFE_RAW_TRANSACTION_ARGUMENTS, Transaction::SAFE_TX_VERSION, Transaction::SIGN_SAFE_TRANSACTION_ARGUMENTS, Transaction::XIN_ASSET_ID

Constants included from Tip

Tip::TIP_ACTIONS

Constants included from LegacyTransfer

LegacyTransfer::TRANSFER_ARGUMENTS

Constants included from LegacyTransaction

LegacyTransaction::LEGACY_TX_VERSION, LegacyTransaction::MAINNET_TRANSACTION_ARGUMENTS, LegacyTransaction::MULTISIG_TRANSACTION_ARGUMENTS, LegacyTransaction::RAW_TRANSACTION_ARGUMENTS

Constants included from LegacyMultisig

LegacyMultisig::MULTISIG_REQUEST_ACTIONS

Constants included from LegacyCollectible

LegacyCollectible::COLLECTABLE_REQUEST_ACTIONS, LegacyCollectible::NFT_ASSET_MIXIN_ID

Constants included from Chain

Chain::CHAIN_NAMES, Chain::VAULTA_ASSET_ID, Chain::XIN_ASSET_ID

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Withdraw

#check_address, #create_withdraw_address, #delete_withdraw_address, #get_withdraw_address, #withdraw_addresses, #withdrawals

Methods included from User

#create_safe_user, #create_user, #fetch_users, #migrate_to_safe, #safe_register, #search_user, #user

Methods included from Turn

#turn_servers

Methods included from Transfer

#build_utxos, #create_safe_transfer, #create_transfer, #send_transaction, #send_transaction_until_sufficient, #send_transaction_with_change_outputs

Methods included from Transaction

#build_inscribe_transaction, #build_object_transaction, #build_occupy_transaction, #build_safe_transaction, #create_object_storage_transaction, #create_safe_keys, #create_safe_transaction_request, #estimate_storage_cost, #generate_safe_keys, #request_ghost_recipients_with_trace_id, #safe_transaction, #send_kernel_transaction_from_account, #send_safe_transaction, #sign_safe_transaction, #storage_recipient, #verify_raw_transaction

Methods included from Tip

#encrypt_tip_pin, #get_tip_node, #tip_body, #tip_body_for_address_add, #tip_body_for_emergency_contact_create, #tip_body_for_ownership_transfer, #tip_body_for_phone_number_update, #tip_body_for_provisioning_update, #tip_body_for_raw_transaction_create, #tip_body_for_sequencer_register, #tip_body_for_transfer, #tip_body_for_verify, #tip_body_for_withdrawal_create, #tip_migrate_body

Methods included from Snapshot

#create_safe_snapshot_notification, #safe_snapshot, #safe_snapshots

Methods included from Session

#fetch_user_sessions

Methods included from Rpc

#get_snapshot, #get_transaction, #get_utxo, #list_mint_distributions, #list_mint_works, #list_snapshots, #rpc_proxy, #send_raw_transaction

Methods included from Pin

#decrypt_pin, #encrypt_pin, #generate_shared_key_with_server, #prepare_tip_key, #update_pin, #update_tip_pin, #verify_pin

Methods included from Payment

#safe_pay_url

Methods included from Output

#build_threshold_script, #safe_output, #safe_outputs

Methods included from NetworkAsset

#network_asset, #network_asset_search, #network_ticker

Methods included from Network

#network_assets, #network_assets_top

Methods included from Multisig

#create_multisig_raw_tx, #create_safe_multisig_request, #safe_multisig_request, #sign_safe_multisig_request, #unlock_safe_multisig_request

Methods included from Message

#acknowledge_message_receipt, #app_button_group, #app_card, #base_message_params, #list_pending_message, #plain_audio, #plain_contact, #plain_data, #plain_image, #plain_post, #plain_sticker, #plain_text, #plain_video, #recall_message, #recall_message_params, #send_app_button_group_message, #send_app_card_message, #send_contact_message, #send_file_message, #send_image_message, #send_message, #send_plain_messages, #send_post_message, #send_text_message, #write_ws_message, #ws_message

Methods included from Me

#friends, #me, #relationship, #safe_me, #update_me, #update_preferences

Methods included from LegacyTransfer

#create_legacy_transfer, #legacy_transfer

Methods included from LegacyTransaction

#build_raw_transaction, #create_mainnet_transaction, #create_multisig_transaction, #transactions

Methods included from LegacySnapshot

#network_snapshot, #network_snapshots, #snapshot, #snapshot_by_trace_id, #snapshots

Methods included from LegacyPayment

#pay_url, #verify_payment

Methods included from LegacyOutput

#build_output, #create_output, #legacy_outputs, #read_multisigs

Methods included from LegacyMultisig

#cancel_multisig_request, #create_multisig_payment, #create_multisig_request, #create_sign_multisig_request, #create_unlock_multisig_request, #sign_multisig_request, #unlock_multisig_request, #verify_multisig

Methods included from LegacyUser

#upgrade_legacy_user

Methods included from LegacyCollectible

#create_collectible_request, #create_sign_collectible_request, #create_unlock_collectible_request, #legacy_collectible, #legacy_collectibles, #legacy_collection, #sign_collectible_request, #unlock_collectible_request

Methods included from Inscription

#collectible, #collectibles, #collection, #collection_collectibles, #create_collectible_transfer

Methods included from Fiat

#fiats

Methods included from EncryptedMessage

#base_encrypted_message_params, #decrypt_message, #encrypt_message, #encrypted_audio, #encrypted_contact, #encrypted_data, #encrypted_image, #encrypted_post, #encrypted_sticker, #encrypted_text, #encrypted_video, #send_encrypted_audio_message, #send_encrypted_contact_message, #send_encrypted_data_message, #send_encrypted_image_message, #send_encrypted_message, #send_encrypted_messages, #send_encrypted_post_message, #send_encrypted_sticker_message, #send_encrypted_text_message, #send_encrypted_video_message

Methods included from Deposit

#pending_safe_deposits

Methods included from Conversation

#add_conversation_participants, #conversation, #conversation_by_user_id, #create_contact_conversation, #create_conversation, #create_group_conversation, #exit_conversation, #join_conversation, #remove_conversation_participants, #rotate_conversation, #unique_uuid, #update_conversation_participants_role, #update_group_conversation_announcement, #update_group_conversation_name

Methods included from ComputerApi

#build_system_call_extra, #computer_deploy_external_asset, #computer_user_id_to_bytes, #decode_computer_extra_base64, #encode_mtg_extra, #encode_operation_memo, #get_computer_deployed_assets, #get_computer_info, #get_computer_system_call, #get_computer_user, #get_fee_on_xin_based_on_sol, #lock_computer_nonce_account, #register_computer

Methods included from Code

#read_code, #read_multisig_by_code

Methods included from Chain

#chain_id?, #chain_name, #full_chains, #network_chain, #network_chains

Methods included from Blaze

#blaze, #blaze_send_app_button, #blaze_send_app_card, #blaze_send_contact, #blaze_send_group_app_button, #blaze_send_plain_text, #blaze_send_post, #blaze_send_recall_message, #start_blaze_connect

Methods included from Auth

#authorization_data, #authorize_code, #oauth_token, #request_oauth, #sign_oauth_access_token

Methods included from Attachment

#attachment, #create_attachment, #upload_attachment

Methods included from Asset

#asset, #asset_balance, #asset_fee, #assets, #fetch_assets, #ticker, #user_asset_balance

Methods included from App

#add_favorite_app, #favorite_apps, #remove_favorite_app, #transfer_app_ownership

Methods included from Address

#safe_deposit_entries

Constructor Details

#initialize(**kwargs) ⇒ API

Initializes a new API instance.

If no parameters are provided, uses the global MixinBot configuration. Otherwise, creates a new configuration with the provided parameters.

Examples:

Using global configuration

api = MixinBot::API.new

With custom configuration

api = MixinBot::API.new(
  app_id: 'your-app-id',
  session_id: 'your-session-id',
  session_private_key: 'your-private-key',
  server_public_key: 'server-public-key'
)

Parameters:

  • kwargs (Hash) —

    configuration options (see Configuration#initialize)

Options Hash (**kwargs):

  • :app_id (String) —

    the application ID

  • :session_id (String) —

    the session ID

  • :session_private_key (String) —

    the session private key

  • :server_public_key (String) —

    the server public key

  • :spend_key (String) —

    the spend private key (for Safe API)



179
180
181
182
183
184
185
186
187
188
 
# File 'lib/mixin_bot/api.rb', line 179

def initialize(**kwargs)
  @config =
    if kwargs.present?
      MixinBot::Configuration.new(**kwargs)
    else
      MixinBot.config
    end

  @client = Client.new(@config)
end

Instance Attribute Details

#client ⇒ MixinBot::Client (readonly)

Returns the HTTP client for making API requests.

Returns:



153
154
155
 
# File 'lib/mixin_bot/api.rb', line 153

def client
  @client
end

#config ⇒ MixinBot::Configuration (readonly)

Returns the configuration for this API instance.

Returns:



149
150
151
 
# File 'lib/mixin_bot/api.rb', line 149

def config
  @config
end

Instance Method Details

#access_token(method, uri, body, **kwargs) ⇒ String Also known as: sign_authentication_token, sign_authentication_token_without_body, sign_authentication_token_with_request_id

Generates an access token for API authentication.

Creates a JWT token signed with the bot’s private key for authenticating API requests. The token includes request details and has a limited lifetime.

Examples:

token = api.access_token('GET', '/me', '')

Parameters:

  • method (String) —

    the HTTP method (GET, POST, etc.)

  • uri (String) —

    the request URI path

  • body (String) —

    the request body

  • kwargs (Hash) —

    additional options

Options Hash (**kwargs):

  • :exp_in (Integer) — default: 600 —

    token expiration time in seconds

  • :scp (String) — default: 'FULL' —

    token scope

Returns:

  • (String) —

    the JWT access token



226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/mixin_bot/api.rb', line 226

def access_token(method, uri, body, **kwargs)
  utils.access_token(
    method,
    uri,
    body,
    exp_in: kwargs.delete(:exp_in) || 600,
    scp: kwargs.delete(:scp) || 'FULL',
    app_id: config.app_id,
    session_id: config.session_id,
    private_key: config.session_private_key
  )
end

#build_collectible_transaction(**kwargs) ⇒ Object 



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/mixin_bot/api/legacy_collectible.rb', line 109

def build_collectible_transaction(**kwargs)
  warn_legacy_mixin_api!('LegacyCollectible#build_collectible_transaction')
  unless COLLECTIBLE_TRANSACTION_ARGUMENTS.all? do |param|
           kwargs.keys.include? param
         end
    raise ArgumentError,
          "#{COLLECTIBLE_TRANSACTION_ARGUMENTS.join(', ')} are needed for build collectible transaction"
  end

  kwargs = kwargs.with_indifferent_access
  collectible = kwargs['collectible']
  raise 'collectible is spent' if collectible['state'] == 'spent'

  build_raw_transaction(
    utxos: [collectible],
    senders: collectible['receivers'],
    senders_threshold: collectible['receivers_threshold'],
    receivers: kwargs['receivers'],
    receivers_threshold: kwargs['receivers_threshold'],
    extra: [kwargs['nfo']].pack('H*'),
    amount: 1,
    asset_mixin_id: NFT_ASSET_MIXIN_ID,
    hint: kwargs['hint']
  )
end

#client_id ⇒ String

Returns the client ID (same as app_id).

Returns:

  • (String) —

    the client ID



204
205
206
 
# File 'lib/mixin_bot/api.rb', line 204

def client_id
  config.app_id
end

#decode_raw_transaction(raw) ⇒ Hash

Decodes a raw transaction to a hash.

Examples:

txn = api.decode_raw_transaction(raw_hex)
puts txn['asset']
puts txn['inputs']

Parameters:

  • raw (String) —

    the hex-encoded raw transaction

Returns:

  • (Hash) —

    the decoded transaction



272
273
274
 
# File 'lib/mixin_bot/api.rb', line 272

def decode_raw_transaction(raw)
  utils.decode_raw_transaction raw
end

#decode_raw_transaction_native(raw) ⇒ Hash

Decodes a raw transaction using native mixin command-line tool.

Requires the ‘mixin’ command to be installed and available in PATH. This is an alternative to the Ruby implementation.

Parameters:

  • raw (String) —

    the hex-encoded raw transaction

Returns:

  • (Hash) —

    the decoded transaction

Raises:

  • (RuntimeError) —

    if mixin command is not available



323
324
325
326
327
328
329
330
331
 
# File 'lib/mixin_bot/api.rb', line 323

def decode_raw_transaction_native(raw)
  ensure_mixin_command_exist
  command = format("mixin decoderawtransaction --raw '%<arg>s'", arg: raw)

  output, error = Open3.capture3(command)
  raise error unless error.empty?

  JSON.parse output.chomp
end

#encode_raw_transaction(txn) ⇒ String

Encodes a transaction hash to raw transaction format.

Examples:

raw = api.encode_raw_transaction(
  version: 5,
  asset: 'asset-id',
  inputs: [...],
  outputs: [...],
  extra: 'memo'
)

Parameters:

  • txn (Hash) —

    the transaction hash with keys: version, asset, inputs, outputs, extra

Returns:

  • (String) —

    the hex-encoded raw transaction



257
258
259
 
# File 'lib/mixin_bot/api.rb', line 257

def encode_raw_transaction(txn)
  utils.encode_raw_transaction txn
end

#encode_raw_transaction_native(json) ⇒ String

Encodes a raw transaction using native mixin command-line tool.

Requires the ‘mixin’ command to be installed and available in PATH. This is an alternative to the Ruby implementation.

Parameters:

  • json (String) —

    the transaction JSON

Returns:

  • (String) —

    the encoded raw transaction

Raises:

  • (RuntimeError) —

    if mixin command is not available



303
304
305
306
307
308
309
310
311
 
# File 'lib/mixin_bot/api.rb', line 303

def encode_raw_transaction_native(json)
  ensure_mixin_command_exist
  command = format("mixin signrawtransaction --raw '%<arg>s'", arg: json)

  output, error = Open3.capture3(command)
  raise error unless error.empty?

  output.chomp
end

#generate_trace_from_hash(hash, output_index = 0) ⇒ String

Generates a trace ID from a transaction hash.

Creates a deterministic UUID trace ID from a transaction hash, useful for tracking outputs from a transaction.

Examples:

trace_id = api.generate_trace_from_hash(tx_hash, 0)

Parameters:

  • hash (String) —

    the transaction hash

  • output_index (Integer) (defaults to: 0) —

    the output index (default: 0)

Returns:

  • (String) —

    the generated trace UUID



289
290
291
 
# File 'lib/mixin_bot/api.rb', line 289

def generate_trace_from_hash(hash, output_index = 0)
  utils.generate_trace_from_hash hash, output_index
end

#nft_memo(collection, token_id, meta) ⇒ Object 



135
136
137
 
# File 'lib/mixin_bot/api/legacy_collectible.rb', line 135

def nft_memo(collection, token_id, meta)
  MixinBot.utils.nft_memo collection, token_id, meta
end

#utils ⇒ Module

Provides access to utility methods.

Returns:

  • (Module) —

    the Utils module



195
196
197
 
# File 'lib/mixin_bot/api.rb', line 195

def utils
  MixinBot::Utils
end