chainalysis 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3559d0827651183fd3adc8bff46df276d1821ee8bf6c16af0be8d7418ad55f5
-  data.tar.gz: ea500373a881c4ff215d04f687d0eb0c18aab2e68237facf4576585ce75facb3
+  metadata.gz: 1983f18acf9c5cbffa2043459bfab6ccecefa84e4dad29669e83428d41a65263
+  data.tar.gz: 3784792d2973049c1e76821605735c4016255ff7b6f9b77ee0cd3ab610dd4d5c
 SHA512:
-  metadata.gz: da082b2fe769d535bb2967c6e49ad40f70a460fb39378eadf3ec1389707c04e7e67942daee81a12f1d506269dc0936b52aeb356afb86feffdfa00adb6970c7a3
-  data.tar.gz: 164c68e2cdea0a703c9887f171c18bcc40c827dbe1eca796faf04820de0e356c919cb9979f4863171cb1c629bd5b69ec547a80dd8b1c07248779ade6fa087b9b
+  metadata.gz: 8ee8e31033ede5e47567edaed216379a3bcb89ef9b597dc7d145c1491fcbab211fecb18f79f725985c81285c53e9b1fb5e4d7419816954d5bf2bb1c0b806cc67
+  data.tar.gz: 2945234b5c597c1012aa47ff5fdfa31f7cc362d7f5c2c0271002571e9c970c9a3f4cbe081b8f45c43d5f55379f12fff51a450fb78c6dcffe0454dfcf863ebfef

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-01-11
+
+- Added support for v1 endpoints
+
 ## [0.1.0] - 2025-01-11
 
 - Initial release

data/README.md

@@ -1,39 +1,160 @@
-# Chainalysis
+# Chainalysis Ruby Client
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/chainalysis`. To experiment with that code, run `bin/console` for an interactive prompt.
+A Ruby wrapper for the Chainalysis Transaction Monitoring API. This client library provides a simple, intuitive interface to interact with Chainalysis's API services.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'chainalysis'
+```
 
-Install the gem and add to the application's Gemfile by executing:
+And then execute:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+$ bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install it yourself as:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+$ gem install chainalysis
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+First, initialize a client with your API key:
+
+```ruby
+require 'chainalysis'
+
+client = Chainalysis::Client.new(api_key: 'your_api_key')
+```
+
+### Registering a Transfer
+
+```ruby
+# Register a new transfer
+response = client.register_transfer(
+  user_id: 'user123',
+  network: 'Bitcoin',
+  asset: 'BTC',
+  transfer_reference: 'tx_hash:address',
+  direction: 'received',
+  # Optional parameters
+  transfer_timestamp: '2024-01-10T15:30:00Z',
+  asset_amount: 1.5,
+  asset_price: 45000.00,
+  asset_denomination: 'USD'
+)
+
+# The response includes an externalId that you can use to query the transfer
+external_id = response['externalId']
+```
+
+### Managing Transfers
+
+```ruby
+# Get transfer details
+transfer = client.get_transfer(external_id: 'transfer_external_id')
+
+# Get transfer exposures
+exposures = client.get_transfer_exposures(external_id: 'transfer_external_id')
+
+# Get transfer alerts
+alerts = client.get_transfer_alerts(external_id: 'transfer_external_id')
+
+# Get transfer network identifications
+identifications = client.get_transfer_network_identifications(external_id: 'transfer_external_id')
+```
+
+### Managing Withdrawal Attempts
+
+```ruby
+# Register a withdrawal attempt
+response = client.register_withdrawal_attempt(
+  user_id: 'user123',
+  network: 'Bitcoin',
+  asset: 'BTC',
+  address: '1EM4e8eu2S2RQrbS8C6aYnunWpkAwQ8GtG',
+  attempt_identifier: 'withdrawal_001',
+  asset_amount: 2.5,
+  attempt_timestamp: '2024-01-10T15:30:00Z'
+)
+
+# Get withdrawal attempt details
+withdrawal = client.get_withdrawal_attempt(external_id: 'withdrawal_external_id')
+
+# Get withdrawal attempt exposures
+exposures = client.get_withdrawal_attempt_exposures(external_id: 'withdrawal_external_id')
+
+# Get withdrawal attempt alerts
+alerts = client.get_withdrawal_attempt_alerts(external_id: 'withdrawal_external_id')
+
+# Get high risk addresses
+addresses = client.get_withdrawal_attempt_high_risk_addresses(external_id: 'withdrawal_external_id')
+
+# Get network identifications
+identifications = client.get_withdrawal_attempt_network_identifications(external_id: 'withdrawal_external_id')
+```
+
+### Categories and Administration
+
+```ruby
+# Get all categories
+categories = client.get_categories
+
+# Get internal users (requires ORGADMIN permission)
+users = client.get_internal_users
+```
+
+## Error Handling
+
+The client includes custom error classes for different types of API errors:
+
+```ruby
+begin
+  client.get_transfer(external_id: 'invalid_id')
+rescue Chainalysis::NotFoundError => e
+  puts "Transfer not found: #{e.message}"
+rescue Chainalysis::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue Chainalysis::RateLimitError => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue Chainalysis::BadRequestError => e
+  puts "Bad request: #{e.message}"
+rescue Chainalysis::ApiError => e
+  puts "API error: #{e.message}"
+end
+```
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Running Tests
+
+```bash
+$ bundle exec rspec
+```
+
+Tests use VCR to record and replay HTTP interactions. To record new interactions, delete the corresponding cassette file and run the tests.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/chainalysis.
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Chainalysis Ruby Client project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/lib/chainalysis/client.rb

@@ -11,10 +11,11 @@ module Chainalysis
   class RateLimitError < Error; end
   class ApiError < Error; end
 
-  class Client
+  # Base client class handling common functionality
+  class BaseClient
     BASE_URL = 'https://api.chainalysis.com/api/kyt'
     ADMIN_URL = 'https://api.chainalysis.com/admin'
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
 
     attr_reader :api_key, :adapter
 
@@ -24,7 +25,171 @@ module Chainalysis
       @stubs = stubs
     end
 
-    # Transfer Registration
+    protected
+
+    def client
+      @client ||= Faraday.new(url: BASE_URL) do |conn|
+        conn.headers['Token'] = api_key
+        conn.headers['Accept'] = 'application/json'
+        conn.headers['Content-Type'] = 'application/json'
+        conn.adapter adapter, @stubs
+      end
+    end
+
+    def admin_client
+      @admin_client ||= Faraday.new(url: ADMIN_URL) do |conn|
+        conn.headers['Token'] = api_key
+        conn.headers['Accept'] = 'application/json'
+        conn.headers['Content-Type'] = 'application/json'
+        conn.adapter adapter, @stubs
+      end
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200, 201, 202
+        return {} if response.body.empty?
+
+        JSON.parse(response.body)
+      when 400
+        raise BadRequestError, error_message(response)
+      when 403
+        raise AuthenticationError, error_message(response)
+      when 404
+        raise NotFoundError, error_message(response)
+      when 429
+        raise RateLimitError, error_message(response)
+      else
+        raise ApiError, error_message(response)
+      end
+    end
+
+    def error_message(response)
+      return response.body if response.body.empty?
+
+      error = JSON.parse(response.body)
+      error['message'] || error['error'] || response.body
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def get_request(url, params = {}, admin: false)
+      client = admin ? admin_client : self.client
+      response = client.get(url) do |req|
+        req.params = params if params
+      end
+      handle_response(response)
+    end
+
+    def post_request(url, body = {})
+      response = client.post(url) do |req|
+        req.body = JSON.generate(body) unless body.empty?
+      end
+      handle_response(response)
+    end
+
+    def delete_request(url)
+      response = client.delete(url)
+      handle_response(response)
+    end
+  end
+
+  # Client for V1 API endpoints
+  class V1Client < BaseClient
+    # Transfer endpoints
+    def register_received_transfer(user_id:, transfers:)
+      post_request("v1/users/#{user_id}/transfers/received", transfers)
+    end
+
+    def get_received_transfers(user_id:, limit: nil, offset: nil)
+      params = {}
+      params[:limit] = limit if limit
+      params[:offset] = offset if offset
+      get_request("v1/users/#{user_id}/transfers/received", params)
+    end
+
+    def register_sent_transfer(user_id:, transfers:)
+      post_request("v1/users/#{user_id}/transfers/sent", transfers)
+    end
+
+    def get_sent_transfers(user_id:, limit: nil, offset: nil)
+      params = {}
+      params[:limit] = limit if limit
+      params[:offset] = offset if offset
+      get_request("v1/users/#{user_id}/transfers/sent", params)
+    end
+
+    # Withdrawal address endpoints
+    def register_withdrawal_addresses(user_id:, addresses:)
+      post_request("v1/users/#{user_id}/withdrawaladdresses", addresses)
+    end
+
+    def get_withdrawal_addresses(user_id:, limit: nil, offset: nil)
+      params = {}
+      params[:limit] = limit if limit
+      params[:offset] = offset if offset
+      get_request("v1/users/#{user_id}/withdrawaladdresses", params)
+    end
+
+    def delete_withdrawal_address(user_id:, asset:, address:)
+      delete_request("v1/users/#{user_id}/withdrawaladdresses/#{asset}/#{address}")
+    end
+
+    # Deposit address endpoints
+    def register_deposit_addresses(user_id:, addresses:)
+      post_request("v1/users/#{user_id}/depositaddresses", addresses)
+    end
+
+    def get_deposit_addresses(user_id:, limit: nil, offset: nil)
+      params = {}
+      params[:limit] = limit if limit
+      params[:offset] = offset if offset
+      get_request("v1/users/#{user_id}/depositaddresses", params)
+    end
+
+    def delete_deposit_address(user_id:, asset:, address:)
+      delete_request("v1/users/#{user_id}/depositaddresses/#{asset}/#{address}")
+    end
+
+    # Alert endpoints
+    def get_alerts(params = {})
+      get_request('v1/alerts/', params)
+    end
+
+    def assign_alert(alert_identifier:, alert_assignee:)
+      post_request("v1/alerts/#{alert_identifier}/assignment",
+                   { alertAssignee: alert_assignee })
+    end
+
+    def update_alert_status(alert_identifier:, status:, comment: nil)
+      body = { status: status }
+      body[:comment] = comment if comment
+      post_request("v1/alerts/#{alert_identifier}/statuses", body)
+    end
+
+    def get_alert_activity(alert_identifier:)
+      get_request("v1/alerts/#{alert_identifier}/activity")
+    end
+
+    # User endpoints
+    def get_users(limit: nil, offset: nil)
+      params = {}
+      params[:limit] = limit if limit
+      params[:offset] = offset if offset
+      get_request('v1/users/', params)
+    end
+
+    def get_user(user_id:)
+      get_request("v1/users/#{user_id}")
+    end
+
+    def rename_users(renames:)
+      post_request('v1/users/rename', renames)
+    end
+  end
+
+  # Client for V2 API endpoints
+  class V2Client < BaseClient
     def register_transfer(user_id:, network:, asset:, transfer_reference:, direction:, **options)
       post_request(
         "v2/users/#{user_id}/transfers",
@@ -38,9 +203,8 @@ module Chainalysis
       )
     end
 
-    # Withdrawal Attempt Registration
-    def register_withdrawal_attempt(user_id:, network:, asset:, address:, attempt_identifier:, asset_amount:,
-                                    attempt_timestamp:, **options)
+    def register_withdrawal_attempt(user_id:, network:, asset:, address:, attempt_identifier:,
+                                    asset_amount:, attempt_timestamp:, **options)
       post_request(
         "v2/users/#{user_id}/withdrawal-attempts",
         {
@@ -55,7 +219,6 @@ module Chainalysis
       )
     end
 
-    # Transfer Endpoints
     def get_transfer(external_id:, format_type: nil)
       params = { format_type: format_type } if format_type
       get_request("v2/transfers/#{external_id}", params)
@@ -73,7 +236,6 @@ module Chainalysis
       get_request("v2/transfers/#{external_id}/network-identifications")
     end
 
-    # Withdrawal Attempt Endpoints
     def get_withdrawal_attempt(external_id:, format_type: nil)
       params = { format_type: format_type } if format_type
       get_request("v2/withdrawal-attempts/#{external_id}", params)
@@ -95,79 +257,23 @@ module Chainalysis
       get_request("v2/withdrawal-attempts/#{external_id}/network-identifications")
     end
 
-    # Categories
     def get_categories
       get_request('v2/categories')
     end
 
-    # Administration
     def get_internal_users
       get_request('organization/users', admin: true)
     end
+  end
 
-    private
-
-    def client
-      @client ||= Faraday.new(url: BASE_URL) do |conn|
-        conn.headers['Token'] = api_key
-        conn.headers['Accept'] = 'application/json'
-        conn.headers['Content-Type'] = 'application/json'
-
-        conn.adapter adapter, @stubs
-      end
-    end
-
-    def admin_client
-      @admin_client ||= Faraday.new(url: ADMIN_URL) do |conn|
-        conn.headers['Token'] = api_key
-        conn.headers['Accept'] = 'application/json'
-        conn.headers['Content-Type'] = 'application/json'
-
-        conn.adapter adapter, @stubs
-      end
-    end
-
-    def handle_response(response)
-      case response.status
-      when 200, 201, 202
-        return {} if response.body.empty?
-
-        JSON.parse(response.body)
-      when 400
-        raise BadRequestError, error_message(response)
-      when 403
-        raise AuthenticationError, error_message(response)
-      when 404
-        raise NotFoundError, error_message(response)
-      when 429
-        raise RateLimitError, error_message(response)
-      else
-        raise ApiError, error_message(response)
-      end
-    end
-
-    def error_message(response)
-      return response.body if response.body.empty?
-
-      error = JSON.parse(response.body)
-      error['message'] || error['error'] || response.body
-    rescue JSON::ParserError
-      response.body
-    end
-
-    def get_request(url, params = {}, admin: false)
-      client = admin ? admin_client : self.client
-      response = client.get(url) do |req|
-        req.params = params if params
-      end
-      handle_response(response)
+  # Main client class that provides access to both V1 and V2 clients
+  class Client < BaseClient
+    def v1
+      @v1 ||= V1Client.new(api_key: api_key, adapter: adapter, stubs: @stubs)
     end
 
-    def post_request(url, body = {})
-      response = client.post(url) do |req|
-        req.body = JSON.generate(body) unless body.empty?
-      end
-      handle_response(response)
+    def v2
+      @v2 ||= V2Client.new(api_key: api_key, adapter: adapter, stubs: @stubs)
     end
   end
 end

data/lib/chainalysis/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chainalysis
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chainalysis
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Raghav Sood