Risk Management

the purpose of this document is to provide an overview of voltage's built in solution for managing lightning risk additionally, it will guide you on how to integrate your own compliance partners and access your transaction data directly our solution amboss reflex https //amboss tech/reflex https //amboss tech/reflex how it works reflex conducts three primary validations—invoice, node pubkey, and lightning address the sections below detail the specific checks performed for each invoice input evaluation process when an invoice is submitted, the system performs a structured sequence of data checks each step ensures that the payment details meet compliance requirements and internal risk controls step 1 extract the destination pubkey 1 1 source of funds check the pubkey is screened against the ofac sanctions list , known ransomware addresses , and any custom address lists configured in the system 1 2 ip address check the destination pubkey ip is verified against ofac country restrictions and any custom country lists 1 3 associated pubkey check the destination pubkey is cross checked with any additional pubkey specific rules or policies configured by the operator step 2 evaluate the route hint pubkey if the invoice includes route hints, each hint undergoes the same set of validations 2 1 source of funds check screened against ofac, ransomware, and custom address lists 2 2 ip address check verified against ofac country restrictions and any custom country list 2 3 associated pubkey check any configured pubkey specific checks are applied step 3 verify the invoice amount the payment amount is compared against a $10,000 standard threshold if a custom threshold is defined by the operator, that value is used instead node pubkey input evaluation process when a node pubkey is provided as input, the system evaluates it by deriving related data and applying layered compliance and risk checks the process follows this sequence step 1 derive peer pubkeys for each peer connected to the input pubkey, the system retrieves associated addresses tor addresses collected but not subject to sanctions or country list checks ip clearnet addresses each address is screened against the ofac sanctions list and any configured custom country list step 2 derive channel ids from the node pubkey, the system gathers all channel ids each channel id is used to identify related onchain addresses step 3 validate onchain addresses for every onchain address linked to a channel id source of funds check the address is screened against the ofac sanctions list , known ransomware addresses , and any custom address lists defined by the operator step 4 determine result after all checks, the system outputs one of the following results pass – all checks were completed with no issues fail – one or more checks identified a compliance or policy violation skipped – the check was not applicable to this input type error – the check could not be completed due to a system or data error lightning address input evaluation process when a lightning address is submitted, the system resolves and validates the underlying details the evaluation process includes the following steps step 1 resolve lightning address the system parses the lightning address to confirm it is properly formatted and valid step 2 derive server ip address the server hosting the lightning address is identified by its ip address this ip is subject to compliance and risk screening (e g , against ofac or custom country lists if configured) step 3 retrieve invoice data once the lightning address is resolved, the system requests an invoice and performs further checks destination pubkey any associated pubkeys are identified and validated according to configured pubkey checks route hint pubkey any associated pubkeys are also derived and validated according to the same checks step 4 determine result based on the outcomes of all validations, the system assigns one of four results pass – all checks were completed successfully fail – one or more checks identified a compliance or policy violation skipped – the check did not apply to this input type error – the evaluation could not be completed due to a system or data error other lightning risk management solutions chainalysis https //www chainalysis com/platform/ https //www chainalysis com/platform/ notabene https //notabene id/ https //notabene id/ accessing transactions data through the ui your voltage payments solution will be made up of one or more "wallets" which our housed within your "environment" see wallet setup guide docid\ alpqa ayg179ccwgf2ija each wallet holds the full transaction history and details for itself within the wallet ui wallet transactions you can click on each transaction to reveal it's full details, history, and lifecycle payment details payment history accessing transactions data through the api get all payments endpoint get /organizations/{organization id}/environments/{environment id}/payments required headers x api key your api key query parameters (all optional) offset pagination offset (integer) limit number of results (integer) wallet id filter by specific wallet (uuid) statuses filter by payment status (array) sort key sort by created at or updated at sort order asc or desc kind payment type bolt11, onchain, bip21 direction send or receive start date / end date date range filter (iso format) example request curl 'https //voltageapi com/v1/organizations/{org id}/environments/{env id}/payments?limit=10\&sort order=desc' \\ \ header 'x api key your api key' response format { "items" \[ { "id" "payment uuid", "status" "completed|sending|receiving|failed", "type" "bolt11|onchain|bip21", "direction" "send|receive", "currency" "btc", "created at" "2024 11 21t18 47 04 008z", "updated at" "2024 11 21t18 47 04 008z", "wallet id" "wallet uuid", "data" { // payment specific details (varies by type) }, "error" null } ], "total" 4, "offset" 0, "limit" 100 } get single payment details endpoint get /organizations/{organization id}/environments/{environment id}/payments/{payment id} example request curl 'https //voltageapi com/v1/organizations/{org id}/environments/{env id}/payments/{payment id}' \\ \ header 'x api key your api key' response single payment object with same structure as above get payment history endpoint get /organizations/{organization id}/environments/{environment id}/payments/{payment id}/history example request curl 'https //voltageapi com/v1/organizations/{org id}/environments/{env id}/payments/{payment id}/history' \\ \ header 'x api key your secret token' data structure by payment type lightning (bolt11) "data" { "amount msats" 150000, "max fee msats" 1000, "memo" "testing", "payment request" "lntbs1500n1p " } on chain "data" { "address" "tb1pzkhtj4ld86g9c ", "amount sats" 150000, "fees sats" 10, "max fee sats" 1000, "receipts" \[ { "amount sats" 10000, "height mined at" 1888021, "tx id" "a22ec88f7a84a705 " } ] } response codes 200 success 400 bad request format 403 no access (requires organization read access) 404 payment not found 500 server error example chainalysis integration key endpoints transfers post /v2/users/{userid}/transfers post /v1/users/{userid}/transfers/sent withdrawal attempts post /v2/users/{userid}/withdrawal attempts post /v1/users/{userid}/withdrawaladdresses required request properties when registering ln transfers, the following properties must be specified additional notes transferreference this must be formatted as payment hash\ node key the payment hash can be obtained from the bolt11 invoice transfertimestamp this is crucial for identifying the usd value of the bitcoin transferred and generating alerts assetamount this value must be in bitcoin optional request properties while not required, the following properties can be included without causing errors outputaddress use the node key instead of a standard wallet address assetprice and assetdenomination these can be sent but will not be returned in subsequent get requests example curl command to register a sent ln transfer using the v2 endpoint $ curl x post 'https //api chainalysis com/api/kyt/v2/users/new user 01/transfers' \\ \ header 'token {your api key}' \\ \ header 'content type application/json' \\ \ data '{ "network" "lightning", "asset" "btc", "transferreference" "2db4d5579a0e198bd5ce8ffe83ecd0de94acde98cde94125337e2419ebb4cc50 02a0c9089ace681ef4e6ae5310b028d9c2a09187bfbc616da6251e3d08801851b8", "direction" "sent", "transfertimestamp" "2021 11 25t11 48 21 000000", "assetamount" " 00588" }' to register the same transfer using the v1 endpoint $ curl x post 'https //api chainalysis com/api/kyt/v1/users/new user 01/transfers/sent' \\ \ header 'token {your api key}' \\ \ header 'content type application/json' \\ \ data raw '\[ { "network" "lightning", "asset" "btc", "transferreference" "2db4d5579a0e198bd5ce8ffe83ecd0de94acde98cde94125337e2419ebb4cc50 02a0c9089ace681ef4e6ae5310b028d9c2a09187bfbc616da6251e3d08801851b8", "transfertimestamp" "2021 11 25t11 48 21 000000", "assetamount" " 00588" } ]'