MarketGuard FAQ
  • MarketGuard
    • Client onboarding
    • Client risk profiling
    • Transaction monitoring (KYT)
      • Adding a transaction manually via GUI
      • Adding a transaction manually via CSV
    • Case management
    • Use cases
    • Glossary
    • Integration guide
  • API reference
    • Transactions
    • Addresses
Powered by GitBook
On this page
  1. API reference

Addresses

PreviousTransactions

Last updated 1 year ago

Search for an address

Adding address to address book

Approve address by internal UID

Approve address by external ID

Get an address by internal UID

Approve address by internal UID

post
Authorizations
Path parameters
address_uidstring · uuidRequired
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
post
POST //api/v1/addresses/{address_uid}/approve HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Approve address by external ID

post
Authorizations
Path parameters
external_idstringRequired
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
post
POST //api/v1/addresses/ext/{external_id}/approve HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Get address by internal UID

get
Authorizations
Path parameters
address_uidstring · uuidRequired
Query parameters
formatany ofOptional

Mask of applied formatters for accounts

integerOptional
or
nullOptional
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
get
GET //api/v1/addresses/{address_uid} HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Deactivate address by internal UID

delete
Authorizations
Path parameters
address_uidstring · uuidRequired
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
delete
DELETE //api/v1/addresses/{address_uid} HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Get address by external ID

get
Authorizations
Path parameters
external_idstringRequired
Query parameters
formatany ofOptional

Mask of applied formatters for accounts

integerOptional
or
nullOptional
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
get
GET //api/v1/addresses/ext/{external_id} HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Deactivate address by external ID

delete
Authorizations
Path parameters
external_idstringRequired
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
delete
DELETE //api/v1/addresses/ext/{external_id} HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Adding an address to address book

post
Authorizations
Body
externalIdany ofOptional

External address ID

string · min: 1Optional
or
nullOptional
accountstring · min: 1Required

Banking IBAN or crypto wallet address

accountDetailsobject · AccountdetailsOptional

Additional account details

networkstring · min: 1Required

Network that serves wallet

currencyany ofOptional

Currency or coin for which address is used

string · min: 1Optional
or
nullOptional
directionall ofOptional

Purpose of using address

Default: all
string · enumOptionalPossible values:
ownerTypeall ofRequired

Address owner type

string · enumOptionalPossible values:
ownerUidstring · uuidRequired

Address owner identifier

descriptionany ofOptional

Address explanation

string · min: 1Optional
or
nullOptional
associatedCounterpartyUidany ofOptional

Counterparty identifier with which address is associated

string · uuidOptional
or
nullOptional
isHiddenbooleanOptional

Address is hidden or visible

Default: false
tagsstring[]Optional

Address text labels

Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
422
Validation Error
application/json
post
POST //api/v1/addresses HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 301

{
  "externalId": "text",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "direction": "all",
  "ownerType": "self",
  "ownerUid": "123e4567-e89b-12d3-a456-426614174000",
  "description": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isHidden": false,
  "tags": [
    "text"
  ]
}
{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Update address info by internal UID

patch
Authorizations
Path parameters
address_uidstring · uuidRequired
Body
externalIdany ofOptional

New external address ID

or
nullOptional
descriptionany ofOptional

New address explanation

or
nullOptional
isHiddenany ofOptional

Set address hidden or visible flag

or
nullOptional
tagsany ofOptional

New address text labels

or
nullOptional
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
patch
PATCH //api/v1/addresses/{address_uid} HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "externalId": {
    "value": "text"
  },
  "description": {
    "value": "text"
  },
  "isHidden": {
    "value": true
  },
  "tags": {
    "value": [
      "text"
    ]
  }
}
{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Update address info by external ID

patch
Authorizations
Path parameters
external_idstringRequired
Body
externalIdany ofOptional

New external address ID

or
nullOptional
descriptionany ofOptional

New address explanation

or
nullOptional
isHiddenany ofOptional

Set address hidden or visible flag

or
nullOptional
tagsany ofOptional

New address text labels

or
nullOptional
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
patch
PATCH //api/v1/addresses/ext/{external_id} HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "externalId": {
    "value": "text"
  },
  "description": {
    "value": "text"
  },
  "isHidden": {
    "value": true
  },
  "tags": {
    "value": [
      "text"
    ]
  }
}
{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Verify address by internal UID

post
Authorizations
Path parameters
address_uidstring · uuidRequired
Body
verificationReasonone ofRequired
or
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
post
POST //api/v1/addresses/{address_uid}/verify HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "verificationReason": {
    "method": null,
    "txHash": "text"
  }
}
{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}

Verify address by external ID

post
Authorizations
Path parameters
external_idstringRequired
Body
verificationReasonone ofRequired
or
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Address not found
application/json
422
Validation Error
application/json
post
POST //api/v1/addresses/ext/{external_id}/verify HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "verificationReason": {
    "method": null,
    "txHash": "text"
  }
}
{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "accountDetails": {},
  "network": "text",
  "currency": "text",
  "assetUid": "123e4567-e89b-12d3-a456-426614174000",
  "direction": "deposit",
  "state": "ownershipPending",
  "description": "text",
  "createdAt": "2025-06-06T22:30:39.935Z",
  "externalId": "text",
  "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "isHidden": true,
  "report": {
    "highRisk": true,
    "provider": "text",
    "riskScore": 1,
    "rawReport": {}
  }
}
  • Search for an address
  • GETSearch addresses
  • Adding address to address book
  • POSTAdding an address to address book
  • Approve address by internal UID
  • POSTApprove address by internal UID
  • Approve address by external ID
  • POSTApprove address by external ID
  • Get an address by internal UID
  • GETGet address by internal UID
  • DELETEDeactivate address by internal UID
  • PATCHUpdate address info by internal UID
  • GETGet address by external ID
  • DELETEDeactivate address by external ID
  • PATCHUpdate address info by external ID
  • POSTVerify address by internal UID
  • POSTVerify address by external ID

Search addresses

get
Authorizations
Query parameters
formatany ofOptional

Mask of applied formatters for accounts

integerOptional
or
nullOptional
cursorany ofOptional

Pointer to next data chunk. Contains filters from first request that override passed filters.

stringOptional
or
nullOptional
uidany ofOptional

Filter by internal address uid

string · uuidOptional
or
nullOptional
externalIdany ofOptional

Filter by external address id

string · min: 1Optional
or
nullOptional
ownerTypeany ofOptional

Filter by address owner type

string · enumOptionalPossible values:
or
nullOptional
ownerUidany ofOptional

Filter by address owner identifier ('ownerType' is required)

string · uuidOptional
or
nullOptional
associatedCounterpartyUidany ofOptional

Filter by counterparty identifier with which address is associated

string · uuidOptional
or
nullOptional
includeNullAssociatedCounterpartybooleanOptional

Whether to include addresses without associated counterparty (used only when filtering by associatedCounterpartyUid)

Default: false
networkany ofOptional

Filter by network that serves wallet

string · min: 1Optional
or
nullOptional
currencyany ofOptional

Filter by currency or coin for which address is used

string · min: 1Optional
or
nullOptional
assetUidany ofOptional

Filter by asset identifier for which address is used

stringOptional
or
nullOptional
accountany ofOptional

Filter by banking IBAN or crypto wallet address ('network' is required)

string · min: 1Optional
or
nullOptional
directionany ofOptional

Filter by purpose of using address

string · enumOptionalPossible values:
or
nullOptional
stateany ofOptional

Filter by address state

string · enumOptionalPossible values:
or
nullOptional
isActiveany ofOptional

Filter by active/inactive addresses

booleanOptional
or
nullOptional
isHiddenany ofOptional

Filter by hidden/visible addresses

booleanOptional
or
nullOptional
tagsstring[]Optional

Filter by address text labels

reportDetailany ofOptional

With what detail to return reports by addresses

string · enumOptionalPossible values:
or
nullOptional
Responses
200
Successful Response
application/json
400
Bad request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
422
Validation Error
application/json
get
GET //api/v1/addresses HTTP/1.1
Host: api.finchguard.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "uid": "123e4567-e89b-12d3-a456-426614174000",
      "account": "text",
      "accountDetails": {},
      "network": "text",
      "currency": "text",
      "assetUid": "123e4567-e89b-12d3-a456-426614174000",
      "direction": "deposit",
      "state": "ownershipPending",
      "description": "text",
      "createdAt": "2025-06-06T22:30:39.935Z",
      "externalId": "text",
      "ownerType": "self",
      "ownerUid": "123e4567-e89b-12d3-a456-426614174000",
      "associatedCounterpartyUid": "123e4567-e89b-12d3-a456-426614174000",
      "verificationReason": {},
      "isActive": true,
      "isHidden": true,
      "report": {
        "highRisk": true,
        "provider": "text",
        "riskScore": 1,
        "rawReport": {}
      }
    }
  ],
  "next": "text"
}