# Transactions * [Supported Assets](#supported-assets) * [API URL](#api-url) * [Authentication](#authentication) * [API Endpoints](#api-endpoints) * [`GET /api/v1/transactions`](#get-api-v1-transactions) * [`GET /api/v1/transactions/:id`](#get-api-v1-transactions-id) * [`PUT /api/v1/transactions/:id`](#put-api-v1-transactions-id) * [Errors](#errors) ## Supported Assets In API responses, you can identify assets using their ticker currency symbol (i.e. `btc`). For a full list of supported assets, see the [Supported Assets](https://balance-1.gitbook.io/balance-custody-api/supported-assets) article. ## API URL You will receive your warm wallet integration URL from your point of contact at Balance, and will look like: ``` YOUR_CUSTOM_SUBDOMAIN.balancecustody.ca ``` *** ## Authentication Due to the nature of the information exposed, every endpoint in this API requires authentication. For more information on authentication go to [Authentication ](https://balance-1.gitbook.io/balance-custody-api/authentication)doc. *** ## API Endpoints For brevity, the `curl` examples below do not include headers. See the `Authentication` section for required headers. Response data is for example purposes only and does not represent real crypto accounts. ### `GET /api/v1/transactions` List all transactions. Includes internal and external transactions. Cursor-based pagination is supported. **Internal** transactions are defined as transactions between your Cold or Warm wallets managed by Balance Custody. **External** transactions are defined as transactions that are originated externally, destined for your Cold or Warm wallets managed by Balance Custody. **Accepted parameters:** Accepts the following GET parameters as part of the query string: **`status`** Optional. Indicates the status of transactions to query for. If not specified, returns all transactions. Possible values are: * `pending_approval` - Transaction is in this state if your warm wallets are set up to require extra approvals before being signed and broadcast by the warm wallets. * `approved` - Transaction is in this state if it has been approved (or auto-approved if your warm wallets do not require extra approvals), but not yet signed and broadcast. * `pending_generation` - Transaction is in this state after a submitted transaction has received all required approvals, while our asynchronous workers are validating and generating transaction data for signing with the wallets. * `completed` - Transaction is in this state after it has been successfully signed and broadcast. * `canceled` - Transaction is in this state if its execution has been canceled through the UI. * `failed` - Transaction is in this state if it its execution failed at any of the steps. In this case the system administrators at Balance are notified and will contact you with next steps. **`regulatory_status`** Optional. Indicates the regulatory status of transactions to query for. This will be used when querying for deposits that require Travel Rule information to be submitted. Possible values are: * `pending` - indicates transactions that have missing Travel Rule information that must be provided. * `completed` - indicates transactions that do not have missing Travel Rule information. **`type`** Optional. Indicates the type of the transaction to query for. If not specified, returns all transactions. Possible values are: * `internal` - Transactions originating from your warm or cold wallets. * `external` - Incoming transactions originating from wallets outside your custody account. **`completed_since`** Optional. If specified, returns *completed transactions only* that were completed after the given timestamp. Completed transactions are defined as external transactions that are confirmed in a block, or internal transactions that have been successfully broadcast. If not specified, returns all transactions. Values are UNIX timestamps (in seconds). **`created_since`** Optional. If specified, returns transactions that were created after the given timestamp. The `created_since` filter refers to the timestamp when a transaction was created or imported in the Balance database, whereas the `completed_since` filter refers to blockchain broadcast or confirmation time of a given transaction. The `created_since` filter can be useful for scanning for transactions that were backfilled or imported long after they were confirmed in a block. Values are UNIX timestamps (in seconds). #### Pagination To request more results provide either a `before` or `after` parameter containing the `cursor` from the transaction you want data prior to or following. For example, to request data after the result in the example below: `GET /api/v1/transactions?after=MTI=` A `page_size` parameter may be provided to control the size of the response. This must be between 1 and 100 and if omitted defaults to 10. **Request** Example without filters: ```bash curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions ``` Example with the `status` filter: ```bash curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions?status=completed ``` Example with completed\_since: ```bash curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions?status=completed\&type=external\&completed_since=1585598824 ``` Example with created\_since: (NOTE: this is the preferred method of polling for incoming external transactions) ```bash curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions?status=completed\&type=external\&created_since=1585598824 ``` **Response** Returns an array of transaction JSON structs. Status: `200` Example of an **Internal** transaction: ```json { "page_info": { "has_previous_page": false, "has_next_page": true, "start_cursor": "MTI=", "end_cursor": "Mw==" }, "page": [ { "cursor": "MTI=", "data": { "id": 1, "type": "transaction", "status": "completed", "created_at": "2019-06-18T19:33:15.000Z", "requested_by": "api", "source": { "id": 1, "type": "wallet", "kind": "warm", "custom_id": "editable custom id 1", "name": "editable name 1", "description": "editable description 1", "balance": { "btc": 12.34567890, "bch": 12.34567890, "ada": 12.34567890, "ltc": 12.34567890, "eth": 12.34567890, "eigen": 12.34567890, "fil": 12.34567890, "xrp": 12.34567890, "xlm": 12.34567890, "usdc": 12.34567890 }, "funding_addresses": { "btc": "1JfQeTopCr1SNk9qoF7qsfCcGtmNUvZdbg", "bch": "1H1NtR2TxvpxVffhh13xKeX2vxENvRJcBZ", "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9", "ltc": "LY5kxT567jCCH6Au1iJHj36ZZKoT5mkeN3", "eth": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4", "eigen": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4", "usdc": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4", "fil": "f1xyexamplefiladdress987654321", "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5", "xlm": "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2" }, "extras": { "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": { "tag": "xrp tag" }, "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": { "memo": "xlm memo" } } }, "amounts": { "btc": 1.23456789, "bch": 1.23456789, "ada": 1.23456789, "ltc": 1.23456789, "eth": 1.23456789, "eigen": 1.23456789, "fil": 1.23456789, "xrp": 1.23456789, "xlm": 1.23456789, "usdc": 1.23456789 }, "fees": { "btc": 0.0002, "bch": 0.0002, "ada": 0.155381, "ltc": 0.0002, "eth": 0.0002, "eigen": 0.0002, "fil": 0.00025202, "xrp": 0.00001, "xlm": 0.00001, "usdc": 0.0002 }, "fee_units": { "btc": "sat/b", "bch": "sat/b", "ada": "ada", "ltc": "sat/b", "eth": "gwei", "eigen": "gwei", "fil": "nanoFIL", "xrp": "xrp/op", "xlm": "xlm/op", "usdc": "gwei" }, "block": { "btc": 1234567, "bch": 1234567, "ada": 1234567, "ltc": 1234567, "eth": 1234567, "eigen": 1234567, "fil": 1234567, "xrp": 1234567, "xlm": 1234567, "usdc": 1234567 }, "cad_rates": { "btc": 123.45, "bch": 123.45, "ada": 1.23, "ltc": 123.45, "eth": 123.45, "eigen": 123.45, "fil": 5.67, "xrp": 0.89, "xlm": 0.17, "usdc": 1.34 }, "notes": "Custom note for this transfer", "completed_at": "2019-06-18T19:33:16.000Z", "transaction_ids": [ { "currency": "btc", "transaction_id": "" }, { "currency": "bch", "transaction_id": "" }, { "currency": "ada", "transaction_id": "" }, { "currency": "ltc", "transaction_id": "" }, { "currency": "eth", "transaction_id": "" }, { "currency": "eigen", "transaction_id": "" }, { "currency": "fil", "transaction_id": "" }, { "currency": "xrp", "transaction_id": "" }, { "currency": "xlm", "transaction_id": "" }, { "currency": "usdc", "transaction_id": "" } ], "destination": { "id": 2, "type": "wallet", "kind": "warm", "custom_id": "editable custom id 2", "name": "editable name 2", "description": "editable description 2", "balance": { "btc": 12.34567890, "bch": 12.34567890, "ada": 12.34567890, "ltc": 12.34567890, "eth": 12.34567890, "eigen": 12.34567890, "fil": 12.34567890, "xrp": 12.34567890, "xlm": 12.34567890, "usdc": 12.34567890 }, "funding_addresses": { "btc": "1EWwLtiDvrLKKf6ySDoKqnFYLvcDMr2TvY", "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi", "ada": "addr1qydz8s47l6zw0u4jeeqzryxjz6j5vzg50t0s5vrqjx9s5rzq7e0u80gkwur", "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE", "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "fil": "f1abexamplefiladdress123456789", "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5", "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO" }, "extras": { "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": { "tag": "xrp tag" }, "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": { "memo": "xlm memo" } } } } }, ... ] } ``` Example of an **Incoming External** transaction: ```json { "page_info": { "has_previous_page": false, "has_next_page": true, "start_cursor": "MTI=", "end_cursor": "Mw==" }, "page": [ { "cursor": "MTI=", "data": { "id": 1, "hash": "", "type": "external", "direction": "incoming", "timestamp": "2019-01-22T01:23:45.000-04:00", "block": 123456, "source_addresses": [ "1H1NtR2TxvpxVffhh13xKeX2vxENvRJcBZ" ], "destination_addresses": [ "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH" ], "destination": { "id": 2, "type": "wallet", "kind": "warm", "custom_id": "editable custom id 2", "name": "editable name 2", "description": "editable description 2", "balance": { "btc": 12.34567890, "bch": 12.34567890, "ada": 12.34567890, "ltc": 12.34567890, "eth": 12.34567890, "eigen": 12.34567890, "fil": 12.34567890, "xrp": 12.34567890, "xlm": 12.34567890, "usdc": 12.34567890 }, "funding_addresses": { "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH", "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi", "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9", "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE", "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "fil": "f1xyexamplefiladdress987654321", "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5", "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO" }, "extras": { "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": { "tag": "xrp tag" }, "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": { "memo": "xlm memo" } } }, "amount": 123.4567890, "fee": 0.12345678, "fee_unit": "sat/b", "currency": "bch" } }, ... ] } ``` Example of an **Outgoing External** transaction: ```json { "page_info": { "has_previous_page": false, "has_next_page": true, "start_cursor": "MTI=", "end_cursor": "Mw==" }, "page": [ { "cursor": "MTI=", "data": { "id": 1, "type": "transaction", "status": "completed", "created_at": "2019-11-18T20:26:51.000Z", "requested_by": "api", "source": { "id": 1, "type": "wallet", "kind": "warm", "custom_id": "Source Wallet Custom Id", "name": "Source Wallet Name", "description": "Source Wallet Description", "balance": { "btc": 12.34567890, "bch": 12.34567890, "ada": 12.34567890, "ltc": 12.34567890, "eth": 12.34567890, "eigen": 12.34567890, "fil": 12.34567890, "xrp": 12.34567890, "xlm": 12.34567890, "usdc": 12.34567890 }, "funding_addresses": { "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH", "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi", "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9", "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE", "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "fil": "f1xyexamplefiladdress987654321", "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5", "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO" }, "extras": { "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": { "tag": "xrp tag" }, "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": { "memo": "xlm memo" } } }, "amounts": { "btc": 1.23456789, "bch": 1.23456789, "ada": 1.23456789, "ltc": 1.23456789, "eth": 1.23456789, "eigen": 1.23456789, "fil": 1.23456789, "xrp": 1.23456789, "xlm": 1.23456789, "usdc": 1.23456789 }, "fees": { "btc": 0.0002, "bch": 0.0002, "ada": 0.155381, "ltc": 0.0002, "eth": 0.0002, "eigen": 0.0002, "fil": 0.00025202, "xrp": 0.00001, "xlm": 0.00001, "usdc": 0.0002 }, "fee_units": { "btc": "sat/b", "bch": "sat/b", "ada": "ada", "ltc": "sat/b", "eth": "gwei", "eigen": "gwei", "fil": "nanoFIL", "xrp": "xrp/op", "xlm": "xlm/op", "usdc": "gwei" }, "block": { "btc": 1234567, "bch": 1234567, "ada": 1234567, "ltc": 1234567, "eth": 1234567, "eigen": 1234567, "fil": 1234567, "xrp": 1234567, "xlm": 1234567, "usdc": 1234567 }, "cad_rates": { "btc": 123.45, "bch": 123.45, "ada": 1.23, "ltc": 123.45, "eth": 123.45, "eigen": 123.45, "fil": 5.67, "xrp": 0.89, "xlm": 0.17, "usdc": 1.34 }, "notes": "Transaction Notes", "completed_at": "2019-11-18T20:26:51.000Z", "transaction_ids": [ { "currency": "btc", "transaction_id": "" }, { "currency": "bch", "transaction_id": "" }, { "currency": "ada", "transaction_id": "" }, { "currency": "ltc", "transaction_id": "" }, { "currency": "eth", "transaction_id": "" }, { "currency": "eigen", "transaction_id": "" }, { "currency": "fil", "transaction_id": "" }, { "currency": "xrp", "transaction_id": "" }, { "currency": "xlm", "transaction_id": "" }, { "currency": "usdc", "transaction_id": "" } ], "destination": { "id": 1, "type": "external_account", "custom_id": "Destination Wallet Custom Id", "name": "Destination Wallet Name", "description": "Destination Wallet Description", "addresses": { "bch": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH" } } } }, ... ] } ``` ### `GET /api/v1/transactions/:id` List details for an individual transaction. No parameters accepted. NOTE: the `id` argument can be defined as one of two things: 1. the ID of an internal transaction (i.e. an integer) 2. the Hash of an externally originated transaction (i.e. a string) **Internal Transaction** **Request** ```bash curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions/1 ``` **Response** Returns a transaction JSON struct. Status: `200` Data: ```json { "id": 1, "type": "transaction", "status": "completed", "created_at": "2025-04-09T18:51:35.000Z", "requested_by": "Operator", "source": { "id": 201, "type": "wallet", "kind": "warm", "custom_id": "Internal Wallet A", "name": "Internal Wallet A", "description": "Source wallet for internal transfer", "balance": { "btc": 12.34567890, "bch": 12.34567890, "ada": 12.34567890, "ltc": 12.34567890, "eth": 12.34567890, "eigen": 12.34567890, "usdc": 12.34567890, "fil": 12.34567890, "xrp": 12.34567890, "xlm": 12.34567890 }, "funding_addresses": { "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH", "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi", "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9", "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE", "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "fil": "f1xyexamplefiladdress987654321", "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5", "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO" } }, "amounts": { "ltc": 0.0003 }, "fees": { "ltc": 0.000004 }, "fee_units": { "ltc": "sat/b" }, "block": { "ltc": 2876792 }, "cad_rates": { "btc": 123.45, "bch": 123.45, "ada": 0.90, "ltc": 110.53, "eth": 123.45, "eigen": 0.99, "usdc": 1.00, "fil": 3.58, "xrp": 0.66, "xlm": 0.13 }, "notes": null, "is_batched": false, "completed_at": "2025-04-09T18:52:09.000Z", "transaction_ids": [ { "currency": "ltc", "transaction_id": "8bfd1142ab5a237605e546124116bc6c5ec665ffa8d5ac4ba33798a593b39608" } ], "destination": { "id": 202, "type": "wallet", "kind": "warm", "custom_id": "Internal Wallet B", "name": "Internal Wallet B", "description": "Destination wallet for internal transfer", "balance": { "btc": 12.34567890, "bch": 12.34567890, "ada": 12.34567890, "ltc": 12.34567890, "eth": 12.34567890, "eigen": 12.34567890, "usdc": 12.34567890, "fil": 12.34567890, "xrp": 12.34567890, "xlm": 12.34567890 }, "funding_addresses": { "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH", "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi", "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9", "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE", "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "fil": "f1xyexamplefiladdress987654321", "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5", "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO" } }, "regulatory_status": "not_required", "originator_entity": { "kind": "corporate", "address1": "123 Example Lane", "address2": "Floor 2", "city": "Toronto", "state": "Ontario", "postcode": "M5V 2Y1", "country": "Canada", "corporate_name": "Demo Originator Inc.", "incorporation_number": "ABC123456", "nature_of_business": "Digital asset services", "id_doc_type_code": 3, "id_doc_number": "ABC123456", "id_doc_jurisdiction_country": "Canada", "id_doc_jurisdiction_state": "Ontario", "registration_country": "Canada", "registration_state": "Ontario", "authorized_person_first_name": "John", "authorized_person_last_name": "Smith" }, "beneficiary_entity": { "kind": "corporate", "address1": "123 Example Lane", "address2": "Floor 2", "city": "Toronto", "state": "Ontario", "postcode": "M5V 2Y1", "country": "Canada", "corporate_name": "Demo Beneficiary Inc.", "incorporation_number": "XYZ987654", "nature_of_business": "Digital asset services", "id_doc_type_code": 3, "id_doc_number": "XYZ987654", "id_doc_jurisdiction_country": "Canada", "id_doc_jurisdiction_state": "Ontario", "registration_country": "Canada", "registration_state": "Ontario", "authorized_person_first_name": "Alice", "authorized_person_last_name": "Johnson" }, "beneficiary_entities": [ { "kind": "corporate", "address1": "123 Example Lane", "address2": "Floor 2", "city": "Toronto", "state": "Ontario", "postcode": "M5V 2Y1", "country": "Canada", "corporate_name": "Demo Beneficiary Inc.", "incorporation_number": "XYZ987654", "nature_of_business": "Digital asset services", "id_doc_type_code": 3, "id_doc_number": "XYZ987654", "id_doc_jurisdiction_country": "Canada", "id_doc_jurisdiction_state": "Ontario", "registration_country": "Canada", "registration_state": "Ontario", "authorized_person_first_name": "Alice", "authorized_person_last_name": "Johnson" } ] } ``` **Off-chain Reconciliation Transaction** Such transaction is only possible when Delivery by Ledger Entry is enabled, and off-chain transactions are reconciled on-chain. The returned data is the same as the **Internal Transaction** above, with two additional fields included: ```json "is_offchain_reconciliation": true, # signifies that this transaction is an off-chain reconciliation transaction "reconciled_transaction_ids": [1,2,3], # returns the off-chain transaction IDs that were reconciled by this transaction "triggered_by_transaction_id": 1, # returns the ID of the transaction that triggered this reconcilication; note that this might be nil if a reconciliation was initiated manually ``` **Transactions that require reconciliation** If a transaction requires reconciling off-chain balances between two or more wallets, the following field will be made available: ```json "reconciling_transaction_ids": [1,2,3] # signifies IDs of reconciliation transactions that were required to enable this transfer ``` **External Transaction** **Request** ```bash curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions/021d6eb3a0a63d857619879a6f8b04124d75725d09d726fddec286829d4c7785 ``` **Response** Returns a transaction JSON struct. Status: `200` Example of an **Incoming External** transaction: Data: ```json { "id": 1, "hash": "abcdef1234567890deadbeef1234567890abcdef1234567890abcdef12345678", "type": "external", "direction": "incoming", "timestamp": "2025-01-01T12:34:56.000Z", "block": 654321, "source_addresses": [ "GDSAMPLEINCOMINGADDRESS1234567890" ], "destination_addresses": [ "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2" ], "destination": { "id": 2, "type": "wallet", "kind": "warm", "custom_id": "editable custom id 2", "name": "editable name 2", "description": "editable description 2", "balance": { "btc": 12.34567890, "bch": 12.34567890, "ltc": 12.34567890, "dash": 12.34567890, "eth": 12.34567890, "etc": 12.34567890, "xrp": 12.34567890, "xlm": 12.34567890, "pax": 12.34567890, "usdc": 12.34567890 }, "funding_addresses": { "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH", "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi", "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE", "dash": "Xhwc7iQTKGq28YWjQNPrNCbGV5v6PWj363", "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "etc": "0x4d35262056fb60e00BBc117a6c535f43fe4ED663", "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5", "xlm": "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2", "pax": "0x32D7335171B0b57522D810c264a1264c9509b620", "usdc": "0x01938ba1c4699fd09b116dd3326906661d34170a" }, "extras": { "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": { "tag": "xrp tag" }, "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": { "memo": "xlm memo" } } }, "amount": 123.456789, "fee": 0.000123, "fee_unit": "xlm/op", "currency": "xlm", "memo": "xlm memo", "regulatory_status": "completed", "beneficiary_entity": { "kind": "corporate", "address1": "123 Example Street", "address2": "Suite 100", "city": "Demo City", "state": "Ontario", "postcode": "M5V1A1", "country": "Canada", "corporate_name": "Example Corp Inc.", "incorporation_number": "ABC1234567", "nature_of_business": "Virtual asset services", "id_doc_type_code": 3, "id_doc_number": "ABC1234567", "id_doc_jurisdiction_country": "Canada", "id_doc_jurisdiction_state": "Ontario", "registration_country": "Canada", "registration_state": "Ontario", "authorized_person_first_name": "Jane", "authorized_person_last_name": "Doe", "is_client_instructed": false }, "beneficiary_entities": [ { "kind": "corporate", "address1": "123 Example Street", "address2": "Suite 100", "city": "Demo City", "state": "Ontario", "postcode": "M5V1A1", "country": "Canada", "corporate_name": "Example Corp Inc.", "incorporation_number": "ABC1234567", "nature_of_business": "Virtual asset services", "id_doc_type_code": 3, "id_doc_number": "ABC1234567", "id_doc_jurisdiction_country": "Canada", "id_doc_jurisdiction_state": "Ontario", "registration_country": "Canada", "registration_state": "Ontario", "authorized_person_first_name": "Jane", "authorized_person_last_name": "Doe", "is_client_instructed": false } ] } ``` Note: the `beneficiary_entity` field has been deprecated. It will only return the most recently assigned beneficiary entity for a transaction. Instead use the field `beneficiary_entities` which is an array containing all beneficiary entities assigned to the transaction. Example of an **Outgoing External** transaction: Data: ```json { "id": 1, "type": "transaction", "status": "completed", "created_at": "2024-12-01T12:00:00.000Z", "requested_by": "Jane Demo", "source": { "id": 888, "type": "wallet", "kind": "warm", "custom_id": "Demo Wallet 001", "name": "Demo Wallet 001", "description": "Used in transaction examples", "balance": { "btc": 12.34567890, "bch": 12.34567890, "ada": 12.34567890, "ltc": 12.34567890, "eth": 12.34567890, "eigen": 12.34567890, "usdc": 12.34567890, "fil": 12.34567890, "xrp": 12.34567890, "xlm": 12.34567890 }, "onchain_balance": { "btc": 12.34567890, "bch": 12.34567890, "ada": 12.34567890, "ltc": 12.34567890, "eth": 12.34567890, "eigen": 12.34567890, "usdc": 12.34567890, "fil": 12.34567890, "xrp": 12.34567890, "xlm": 12.34567890 }, "funding_addresses": { "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH", "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi", "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9", "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE", "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09", "fil": "f1xyexamplefiladdress987654321", "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5", "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO" }, "owner": { "address1": "123 Demo Ave.", "address2": "Suite 456", "city": "Exampleville", "state": "Testland", "postcode": "X0X 0X0", "country": "Demo Country", "corporate_name": "Demo Custody Inc." } }, "amounts": { "eth": 0.0025 }, "cad_rates": { "btc": 95000.0, "bch": 625.0, "ada": 0.62, "ltc": 110.0, "eth": 4850.0, "eigen": 4.50, "usdc": 1.37, "fil": 7.48, "xrp": 0.72, "xlm": 0.13 }, "notes": "Example transaction", "is_batched": false, "completed_at": "2024-12-01T12:00:12.000Z", "transaction_ids": [ { "currency": "eth", "transaction_id": "0xb783de71f27a49911d3f3b7d0d6303d40e5e8fca71b84123bfea8ad8f9dc99ab" } ], "destination": { "id": 889, "name": "Demo External Account", "custom_id": "external-001", "description": "Destination for ETH", "type": "external_account", "addresses": { "eth": "0x4d9739cc9e3b9eabc302e78d7f9e283f002233f1" } }, "fees": { "eth": 0.00045 }, "fee_units": { "eth": "gwei" }, "block": { "eth": 20999999 }, "regulatory_status": "not_required", "originator_entity": { "kind": "corporate", "address1": "123 Demo Ave.", "address2": "Suite 456", "city": "Exampleville", "state": "Testland", "postcode": "X0X 0X0", "country": "Demo Country", "corporate_name": "Demo Custody Inc.", "incorporation_number": "999999-9", "nature_of_business": "Digital asset custody", "id_doc_type_code": 3, "id_doc_number": "999999-9", "id_doc_jurisdiction_country": "Demo Country", "id_doc_jurisdiction_state": "Testland", "registration_country": "Demo Country", "registration_state": "Testland", "authorized_person_first_name": "Jane", "authorized_person_last_name": "Demo" } } ``` ### `PUT /api/v1/transactions/:id` Update details of a transaction with a given ID. Currently, you are only able to update regulatory compliance fields for external deposits. NOTE: the `id` argument can be defined as one of two things: 1. the ID of an internal transaction (i.e. an integer) 2. the Hash of an externally originated transaction (i.e. a string) **Accepted parameters:** * `is_originator_declared` - a boolean; if provided, and set to `false` - then your organization information is used as an Originator Entity, and no further parameters for Originator Entity are required. * `originator_entity` - an object of type Originator Entity. Signifies the originator of the deposit. Only persisted if the destination wallet does not already have a default originator entity set, and if the deposit does not already have an originator entity set. You should aim to provide all available information. The Balance Custody platform will make a determination about whether the information you provided is sufficient for the current transaction, and return a response code 200 if it is. If the information is insufficient, a 400 response code will be returned, along with an error message describing the missing field. * `third_party_entity` - an object of type Third Party Entity. Signifies the third party that instructed this deposit to be made. Only persisted if the deposit does not already have a third party entity set. You should aim to provide all available information. The Balance Custody platform will make a determination about whether the information you provided is sufficient for the current transaction, and return a response code 200 if it is. If the information is insufficient, a 400 response code will be returned, along with an error message describing the missing field. * `is_client_instructed` - a boolean; default is 'false'; should be set to 'true' if one of your clients instructed this deposit for the provision of goods and services on your platform **Request** ```bash curl -XPUT \ -d '{"originator_entity":{"firstname":"John","lastname":"Smith","address1":"1 King Road","address2":"Unit 30","city":"Toronto","state":"Ontario","postcode":"1A2 3B4","country":"Canada","account_id":"123-123123"}}' \ https://your_custom_subdomain.balancecustody.ca/api/v1/transactions/1 ``` **Response** Same response as [`GET /api/v1/transactions/:id`](#get-api-v1-transactions-id) ## Errors Errors in this API are the same as the ones specified in the [wallet API](https://balance-1.gitbook.io/balance-custody-api/v1/wallets) docs.