> For the complete documentation index, see [llms.txt](https://axiology.gitbook.io/axiology-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiology.gitbook.io/axiology-docs/rest-api/equities.md).

# Equities

## GET /equities

> Retrieve a list of equities available in the system

```json
{"openapi":"3.1.0","info":{"title":"Axiology TSS Broker Node API","version":"0.0.1"},"paths":{"/equities":{"get":{"description":"Retrieve a list of equities available in the system","operationId":"getEquities","parameters":[{"name":"filter","required":false,"in":"query","style":"deepObject","explode":true,"schema":{"$ref":"#/components/schemas/FilterEquityDto"}},{"name":"mode","required":false,"in":"query","description":"Strategy applied when filtering/searching on multiple fields","schema":{"$ref":"#/components/schemas/FilterMode"}},{"name":"pagination","required":false,"in":"query","style":"deepObject","explode":true,"schema":{"$ref":"#/components/schemas/PaginationRequestDto"}},{"name":"order","required":false,"in":"query","content":{"application/json":{"schema":{"type":"array","uniqueItems":true,"items":{"type":"object","oneOf":[{"properties":{"createdAt":{"type":"string","enum":["asc","desc"]}},"required":["createdAt"]},{"properties":{"nominalValue":{"type":"string","enum":["asc","desc"]}},"required":["nominalValue"]},{"properties":{"issueDate":{"type":"string","enum":["asc","desc"]}},"required":["issueDate"]},{"properties":{"status":{"type":"string","enum":["asc","desc"]}},"required":["status"]},{"properties":{"name":{"type":"string","enum":["asc","desc"]}},"required":["name"]},{"properties":{"supply":{"type":"string","enum":["asc","desc"]}},"required":["supply"]},{"properties":{"undistributedAmount":{"type":"string","enum":["asc","desc"]}},"required":["undistributedAmount"]}]}}}},"description":"Array of fields and directions to order. Supported fields: createdAt, nominalValue, issueDate, status, name, supply, undistributedAmount"}],"responses":{"200":{"description":"Successfully retrieved a list of items.","content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/PaginationResponseDto"},"items":{"type":"array","items":{"$ref":"#/components/schemas/EquityDto"}}},"required":["pagination","items"]}}}}},"summary":"","tags":["Equities"]}}},"components":{"schemas":{"FilterEquityDto":{"type":"object","properties":{"id":{"description":"Filter equities by id","oneOf":[{"type":"array","items":{"description":"Unique UUIDs of an entity","format":"uuid","type":"string"},"minItems":1},{"description":"Unique UUID of an entity","format":"uuid","type":"string"}]},"currencyId":{"description":"Filter equities by currency id","oneOf":[{"type":"array","items":{"description":"Unique UUIDs of an entity","format":"uuid","type":"string"},"minItems":1},{"description":"Unique UUID of an entity","format":"uuid","type":"string"}]},"issuerId":{"description":"Filter equities by issuer id","oneOf":[{"type":"array","items":{"description":"Unique UUIDs of an entity","format":"uuid","type":"string"},"minItems":1},{"description":"Unique UUID of an entity","format":"uuid","type":"string"}]},"nominalValue":{"type":"number","description":"Filter equities by nominal value"},"issueDate":{"format":"date-time","description":"Filter equities by issue date","oneOf":[{"type":"array","items":{"type":"string","format":"date-time"},"minItems":1,"maxItems":2},{"type":"string","format":"date-time"}]},"status":{"description":"Filter equities by status","oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/EquityStatus"},"minItems":1},{"$ref":"#/components/schemas/EquityStatus"}]},"issuingAccountAddress":{"description":"Filter equities by issuer address","oneOf":[{"type":"array","items":{"description":"Account address","type":"string","format":"xrp-address","pattern":"r[0-9a-zA-Z]{24,34}"},"minItems":1},{"type":"string","description":"Partial account address"}]},"operationalAccountAddress":{"description":"Filter equities by operational account address","oneOf":[{"type":"array","items":{"description":"Account address","type":"string","format":"xrp-address","pattern":"r[0-9a-zA-Z]{24,34}"},"minItems":1},{"type":"string","description":"Partial account address"}]},"name":{"type":"string","description":"Filter equities by name"},"supply":{"description":"Filter equities by supply from number or between two numbers","oneOf":[{"type":"array","items":{"type":"integer","format":"int64"},"minItems":1,"maxItems":2},{"type":"integer","format":"int64"}]},"specUrl":{"type":"string","description":"Filter equities by specification URL"},"isin":{"type":"string","description":"Filter equities by isin"}}},"EquityStatus":{"type":"string","enum":["recorded","live","suspended","closed"],"description":"Status of equity"},"FilterMode":{"type":"string","enum":["and","or"]},"PaginationRequestDto":{"type":"object","properties":{"size":{"type":"number","minimum":1,"default":10},"page":{"type":"number","minimum":1,"default":1}}},"PaginationResponseDto":{"type":"object","properties":{"size":{"type":"number","minimum":1,"default":10},"page":{"type":"number","minimum":1,"default":1},"totalItems":{"type":"number","description":"Total items count"},"totalPages":{"type":"number","description":"Total pages count"}},"required":["totalItems","totalPages"]},"EquityDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"Created date"},"updatedAt":{"format":"date-time","type":"string","description":"Updated date"},"id":{"type":"string","description":"Equity UUID identifier, global in scope of TSS","format":"uuid"},"currencyId":{"type":"string","description":"Unique UUID of the currency equity in scope of this gateway","format":"uuid"},"issuerId":{"type":"string","description":"Unique UUID of issuer in scope of this gateway","format":"uuid"},"nominalValue":{"format":"int64","description":"Price of ONE share.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"issueDate":{"type":"string","description":"Issue registration date"},"status":{"description":"Status of equity","allOf":[{"$ref":"#/components/schemas/EquityStatus"}]},"issuingAccountAddress":{"type":"string","description":"Issuing account address"},"operationalAccountAddress":{"type":"string","description":"Operational account address"},"name":{"type":"string","description":"A user friendly name of the asset (ex. Orange Bond)"},"supply":{"format":"int64","description":"Total supply of the asset that exists amongst all platforms together.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"specUrl":{"type":"string","description":"IPFS link"},"isin":{"type":"string","description":"An International Securities Identification Number","nullable":true},"ecbClassification":{"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists.","allOf":[{"$ref":"#/components/schemas/PAC2"}]},"undistributedAmount":{"format":"int64","description":"Undistributed amount of the equity placed in warm wallet\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]}},"required":["createdAt","updatedAt","id","currencyId","issuerId","nominalValue","issueDate","status","issuingAccountAddress","operationalAccountAddress","name","supply","specUrl","isin","ecbClassification","undistributedAmount"]},"ExponentScaledDecimal":{"type":"integer","format":"int64","description":"Decimal value encoded on the wire as an integer scaled by the asset's exponent: `encoded = real × 10^exponent`. E.g. for a bond denominated in EUR (exponent=2), a coupon payment of `123.45` is encoded as `12345`, and a nominal value of `1000.00` is encoded as `100000`."},"PAC2":{"type":"string","enum":["C","D","D.1","D.11","D.12","D.121","D.122","D.129","D.13","D.131","D.139","D.14","D.141","D.149","D.15","D.16","D.161","D.162","D.163","D.164","D.165","D.166","D.167","D.169","D.17","D.171","D.172","D.18","D.181","D.1811","D.1812","D.1813","D.1819","D.182","D.1821","D.1822","D.1823","D.1829","D.19","D.2","D.21","D.22","D.23","D.231","D.232","D.239","D.24","D.29","D.3","D.31","D.311","D.32","D.33","D.34","D.39","D.9","E","E.1","E.2","E.21","E.22","E.23","E.24","E.29","E.3","E.31","E.32","E.39","E.4","E.41","E.42","E.43","E.49","E.9","F","F.1","F.2","F.9","I","L","M","O","P","R","U"],"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists."}}}}
```

## POST /equities

> Create a new equity. Prepares blockchain accounts and issues provided total supply from cold to warm wallet. Makes equity ready for distribution.

```json
{"openapi":"3.1.0","info":{"title":"Axiology TSS Broker Node API","version":"0.0.1"},"paths":{"/equities":{"post":{"description":"Create a new equity. Prepares blockchain accounts and issues provided total supply from cold to warm wallet. Makes equity ready for distribution.","operationId":"createEquity","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEquityDto"}}}},"responses":{"201":{"description":"Successfully created an equity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquityDto"}}}}},"summary":"","tags":["Equities"]}}},"components":{"schemas":{"CreateEquityDto":{"type":"object","properties":{"name":{"type":"string","description":"A user friendly name of the asset (ex. Orange Bond)"},"totalSupply":{"format":"int64","description":"Total supply of the asset that exists amongst all platforms together.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"currencyId":{"type":"string","description":"Unique UUID of the currency in scope of this gateway provided","format":"uuid"},"issuerId":{"type":"string","description":"Unique UUID of issuer in scope of this gateway","format":"uuid"},"nominalValue":{"format":"int64","description":"Price of ONE share.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"issueDate":{"format":"date-time","type":"string","description":"Issue registration date"},"isin":{"type":"string","description":"An International Securities Identification Number","nullable":true},"ecbClassification":{"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists.","allOf":[{"$ref":"#/components/schemas/PAC2"}]}},"required":["name","totalSupply","currencyId","issuerId","nominalValue","issueDate","ecbClassification"]},"ExponentScaledDecimal":{"type":"integer","format":"int64","description":"Decimal value encoded on the wire as an integer scaled by the asset's exponent: `encoded = real × 10^exponent`. E.g. for a bond denominated in EUR (exponent=2), a coupon payment of `123.45` is encoded as `12345`, and a nominal value of `1000.00` is encoded as `100000`."},"PAC2":{"type":"string","enum":["C","D","D.1","D.11","D.12","D.121","D.122","D.129","D.13","D.131","D.139","D.14","D.141","D.149","D.15","D.16","D.161","D.162","D.163","D.164","D.165","D.166","D.167","D.169","D.17","D.171","D.172","D.18","D.181","D.1811","D.1812","D.1813","D.1819","D.182","D.1821","D.1822","D.1823","D.1829","D.19","D.2","D.21","D.22","D.23","D.231","D.232","D.239","D.24","D.29","D.3","D.31","D.311","D.32","D.33","D.34","D.39","D.9","E","E.1","E.2","E.21","E.22","E.23","E.24","E.29","E.3","E.31","E.32","E.39","E.4","E.41","E.42","E.43","E.49","E.9","F","F.1","F.2","F.9","I","L","M","O","P","R","U"],"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists."},"EquityDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"Created date"},"updatedAt":{"format":"date-time","type":"string","description":"Updated date"},"id":{"type":"string","description":"Equity UUID identifier, global in scope of TSS","format":"uuid"},"currencyId":{"type":"string","description":"Unique UUID of the currency equity in scope of this gateway","format":"uuid"},"issuerId":{"type":"string","description":"Unique UUID of issuer in scope of this gateway","format":"uuid"},"nominalValue":{"format":"int64","description":"Price of ONE share.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"issueDate":{"type":"string","description":"Issue registration date"},"status":{"description":"Status of equity","allOf":[{"$ref":"#/components/schemas/EquityStatus"}]},"issuingAccountAddress":{"type":"string","description":"Issuing account address"},"operationalAccountAddress":{"type":"string","description":"Operational account address"},"name":{"type":"string","description":"A user friendly name of the asset (ex. Orange Bond)"},"supply":{"format":"int64","description":"Total supply of the asset that exists amongst all platforms together.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"specUrl":{"type":"string","description":"IPFS link"},"isin":{"type":"string","description":"An International Securities Identification Number","nullable":true},"ecbClassification":{"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists.","allOf":[{"$ref":"#/components/schemas/PAC2"}]},"undistributedAmount":{"format":"int64","description":"Undistributed amount of the equity placed in warm wallet\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]}},"required":["createdAt","updatedAt","id","currencyId","issuerId","nominalValue","issueDate","status","issuingAccountAddress","operationalAccountAddress","name","supply","specUrl","isin","ecbClassification","undistributedAmount"]},"EquityStatus":{"type":"string","enum":["recorded","live","suspended","closed"],"description":"Status of equity"}}}}
```

## GET /equities/{equityId}

> Retrieve full information about a single equity, specified by equity id in the path.

```json
{"openapi":"3.1.0","info":{"title":"Axiology TSS Broker Node API","version":"0.0.1"},"paths":{"/equities/{equityId}":{"get":{"description":"Retrieve full information about a single equity, specified by equity id in the path.","operationId":"getEquity","parameters":[{"name":"equityId","required":true,"in":"path","description":"Equity UUID identifier, global in scope of TSS","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Successfully received equity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquityDto"}}}}},"summary":"","tags":["Equities"]}}},"components":{"schemas":{"EquityDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"Created date"},"updatedAt":{"format":"date-time","type":"string","description":"Updated date"},"id":{"type":"string","description":"Equity UUID identifier, global in scope of TSS","format":"uuid"},"currencyId":{"type":"string","description":"Unique UUID of the currency equity in scope of this gateway","format":"uuid"},"issuerId":{"type":"string","description":"Unique UUID of issuer in scope of this gateway","format":"uuid"},"nominalValue":{"format":"int64","description":"Price of ONE share.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"issueDate":{"type":"string","description":"Issue registration date"},"status":{"description":"Status of equity","allOf":[{"$ref":"#/components/schemas/EquityStatus"}]},"issuingAccountAddress":{"type":"string","description":"Issuing account address"},"operationalAccountAddress":{"type":"string","description":"Operational account address"},"name":{"type":"string","description":"A user friendly name of the asset (ex. Orange Bond)"},"supply":{"format":"int64","description":"Total supply of the asset that exists amongst all platforms together.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"specUrl":{"type":"string","description":"IPFS link"},"isin":{"type":"string","description":"An International Securities Identification Number","nullable":true},"ecbClassification":{"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists.","allOf":[{"$ref":"#/components/schemas/PAC2"}]},"undistributedAmount":{"format":"int64","description":"Undistributed amount of the equity placed in warm wallet\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]}},"required":["createdAt","updatedAt","id","currencyId","issuerId","nominalValue","issueDate","status","issuingAccountAddress","operationalAccountAddress","name","supply","specUrl","isin","ecbClassification","undistributedAmount"]},"ExponentScaledDecimal":{"type":"integer","format":"int64","description":"Decimal value encoded on the wire as an integer scaled by the asset's exponent: `encoded = real × 10^exponent`. E.g. for a bond denominated in EUR (exponent=2), a coupon payment of `123.45` is encoded as `12345`, and a nominal value of `1000.00` is encoded as `100000`."},"EquityStatus":{"type":"string","enum":["recorded","live","suspended","closed"],"description":"Status of equity"},"PAC2":{"type":"string","enum":["C","D","D.1","D.11","D.12","D.121","D.122","D.129","D.13","D.131","D.139","D.14","D.141","D.149","D.15","D.16","D.161","D.162","D.163","D.164","D.165","D.166","D.167","D.169","D.17","D.171","D.172","D.18","D.181","D.1811","D.1812","D.1813","D.1819","D.182","D.1821","D.1822","D.1823","D.1829","D.19","D.2","D.21","D.22","D.23","D.231","D.232","D.239","D.24","D.29","D.3","D.31","D.311","D.32","D.33","D.34","D.39","D.9","E","E.1","E.2","E.21","E.22","E.23","E.24","E.29","E.3","E.31","E.32","E.39","E.4","E.41","E.42","E.43","E.49","E.9","F","F.1","F.2","F.9","I","L","M","O","P","R","U"],"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists."}}}}
```

## PATCH /equities/{equityId}

> Issue additional equity tokens or burn existing ones, changing the total supply and, if chosen, nominal value.

```json
{"openapi":"3.1.0","info":{"title":"Axiology TSS Broker Node API","version":"0.0.1"},"paths":{"/equities/{equityId}":{"patch":{"description":"Issue additional equity tokens or burn existing ones, changing the total supply and, if chosen, nominal value.","operationId":"updateEquity","parameters":[{"name":"equityId","required":true,"in":"path","description":"Equity UUID identifier, global in scope of TSS","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEquityDto"}}}},"responses":{"200":{"description":"Equity successfully updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquityDto"}}}}},"summary":"","tags":["Equities"]}}},"components":{"schemas":{"UpdateEquityDto":{"type":"object","properties":{"supply":{"format":"int64","description":"Change supply of the equity to new amount (implies issuing additional equities or burning existing ones).\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"nominalValue":{"format":"int64","description":"New nominal value of the equity. If not provided, will remain the same.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"status":{"description":"**Update equity status:**\n- `closed` - close equity","allOf":[{"$ref":"#/components/schemas/EquityStatus"}]},"ecbClassification":{"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists.","allOf":[{"$ref":"#/components/schemas/PAC2"}]},"name":{"type":"string","description":"A user friendly name of the asset (ex. Orange Bond)"},"reference":{"type":"string","description":"Reference to a document or corporate action number, etc. - anything that could help relate supply or nominal value change with other context"},"recordedAt":{"format":"date-time","type":"string","description":"Day when the action was documented to be executed. This is not necessarily the day when the equity is actually changing supply or nominal value"}},"required":["reference","recordedAt"]},"ExponentScaledDecimal":{"type":"integer","format":"int64","description":"Decimal value encoded on the wire as an integer scaled by the asset's exponent: `encoded = real × 10^exponent`. E.g. for a bond denominated in EUR (exponent=2), a coupon payment of `123.45` is encoded as `12345`, and a nominal value of `1000.00` is encoded as `100000`."},"EquityStatus":{"type":"string","enum":["recorded","live","suspended","closed"],"description":"Status of equity"},"PAC2":{"type":"string","enum":["C","D","D.1","D.11","D.12","D.121","D.122","D.129","D.13","D.131","D.139","D.14","D.141","D.149","D.15","D.16","D.161","D.162","D.163","D.164","D.165","D.166","D.167","D.169","D.17","D.171","D.172","D.18","D.181","D.1811","D.1812","D.1813","D.1819","D.182","D.1821","D.1822","D.1823","D.1829","D.19","D.2","D.21","D.22","D.23","D.231","D.232","D.239","D.24","D.29","D.3","D.31","D.311","D.32","D.33","D.34","D.39","D.9","E","E.1","E.2","E.21","E.22","E.23","E.24","E.29","E.3","E.31","E.32","E.39","E.4","E.41","E.42","E.43","E.49","E.9","F","F.1","F.2","F.9","I","L","M","O","P","R","U"],"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists."},"EquityDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"Created date"},"updatedAt":{"format":"date-time","type":"string","description":"Updated date"},"id":{"type":"string","description":"Equity UUID identifier, global in scope of TSS","format":"uuid"},"currencyId":{"type":"string","description":"Unique UUID of the currency equity in scope of this gateway","format":"uuid"},"issuerId":{"type":"string","description":"Unique UUID of issuer in scope of this gateway","format":"uuid"},"nominalValue":{"format":"int64","description":"Price of ONE share.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"issueDate":{"type":"string","description":"Issue registration date"},"status":{"description":"Status of equity","allOf":[{"$ref":"#/components/schemas/EquityStatus"}]},"issuingAccountAddress":{"type":"string","description":"Issuing account address"},"operationalAccountAddress":{"type":"string","description":"Operational account address"},"name":{"type":"string","description":"A user friendly name of the asset (ex. Orange Bond)"},"supply":{"format":"int64","description":"Total supply of the asset that exists amongst all platforms together.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"specUrl":{"type":"string","description":"IPFS link"},"isin":{"type":"string","description":"An International Securities Identification Number","nullable":true},"ecbClassification":{"description":"**ECB Primary Asset Classification (PAC2)** code used in ECB SHS/SHSG reporting codelists.","allOf":[{"$ref":"#/components/schemas/PAC2"}]},"undistributedAmount":{"format":"int64","description":"Undistributed amount of the equity placed in warm wallet\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]}},"required":["createdAt","updatedAt","id","currencyId","issuerId","nominalValue","issueDate","status","issuingAccountAddress","operationalAccountAddress","name","supply","specUrl","isin","ecbClassification","undistributedAmount"]}}}}
```

## POST /equities/{equityId}/deductions

> Deduct equities from investors.

```json
{"openapi":"3.1.0","info":{"title":"Axiology TSS Broker Node API","version":"0.0.1"},"paths":{"/equities/{equityId}/deductions":{"post":{"description":"Deduct equities from investors.","operationId":"createEquityDeduction","parameters":[{"name":"equityId","required":true,"in":"path","description":"Equity UUID identifier, global in scope of TSS","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEquityDeductionDto"}}}},"responses":{"201":{"description":"Successfully created equity deduction","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EquityDeductionDto"}}}}}},"summary":"","tags":["Equities"]}}},"components":{"schemas":{"CreateEquityDeductionDto":{"type":"object","properties":{"reference":{"type":"string","description":"Reference to a document or corporate action number, etc. - anything that could help relate deduction actions with other context"},"recordedAt":{"format":"date-time","type":"string","description":"Day when the action was documented to be executed. This is not necessarily the day when the equity is actually deducted from the investor."},"deductees":{"description":"Array of accounts to deduct the equity from","type":"array","items":{"$ref":"#/components/schemas/EquityDeducteeDto"}}},"required":["reference","recordedAt","deductees"]},"EquityDeducteeDto":{"type":"object","properties":{"address":{"type":"string","description":"Address of the account to deduct the equity from","format":"xrp-address","pattern":"r[0-9a-zA-Z]{24,34}"},"amount":{"format":"int64","description":"Amount of equity to deduct from the provided account.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]}},"required":["address","amount"]},"ExponentScaledDecimal":{"type":"integer","format":"int64","description":"Decimal value encoded on the wire as an integer scaled by the asset's exponent: `encoded = real × 10^exponent`. E.g. for a bond denominated in EUR (exponent=2), a coupon payment of `123.45` is encoded as `12345`, and a nominal value of `1000.00` is encoded as `100000`."},"EquityDeductionDto":{"type":"object","properties":{"id":{"type":"string","description":"Equity deduction UUID identifier, unique in scope of this node","format":"uuid"},"equityId":{"type":"string","description":"Unique UUID of the equity in scope of this gateway","format":"uuid"},"accountAddress":{"type":"string","description":"Equity`s destination address corresponding to the investor account address","format":"xrp-address","pattern":"r[0-9a-zA-Z]{24,34}"},"amount":{"format":"int64","description":"Amount of equity deducted from the provided investor.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"reference":{"type":"string","description":"Reference to a document or corporate action number, etc. - anything that could help relate deduction actions with other context"},"recordedAt":{"type":"string","description":"Day when the action was documented to be executed. This is not necessarily the day when the equity is actually deducted from the investor."},"status":{"description":"Status of equity deduction action","allOf":[{"$ref":"#/components/schemas/EquityDeductionStatus"}]}},"required":["id","equityId","accountAddress","amount","reference","recordedAt","status"]},"EquityDeductionStatus":{"type":"string","enum":["successful","failed"],"description":"Status of equity deduction action"}}}}
```

## POST /equities/{equityId}/distributions

> Create equity distribution.

```json
{"openapi":"3.1.0","info":{"title":"Axiology TSS Broker Node API","version":"0.0.1"},"paths":{"/equities/{equityId}/distributions":{"post":{"description":"Create equity distribution.","operationId":"createEquityDistribution","parameters":[{"name":"equityId","required":true,"in":"path","description":"Equity UUID identifier, global in scope of TSS","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEquityDistributionDto"}}}},"responses":{"201":{"description":"Successfully created equity distribution","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EquityDistributionDto"}}}}}},"summary":"","tags":["Equities"]}}},"components":{"schemas":{"CreateEquityDistributionDto":{"type":"object","properties":{"reference":{"type":"string","description":"Reference to a document or corporate action number, etc. - anything that could help relate distribution actions with other context"},"recordedAt":{"format":"date-time","type":"string","description":"Day when the action was documented to be executed. This is not necessarily the day when the equity is actually distributed to the investor."},"distributees":{"description":"Array of accounts to distribute the equity to","type":"array","items":{"$ref":"#/components/schemas/EquityDistributeeDto"}}},"required":["reference","recordedAt","distributees"]},"EquityDistributeeDto":{"type":"object","properties":{"address":{"type":"string","description":"Address of the account to distribute the equity to","format":"xrp-address","pattern":"r[0-9a-zA-Z]{24,34}"},"amount":{"format":"int64","description":"Amount of equity to send to the provided receiver.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]}},"required":["address","amount"]},"ExponentScaledDecimal":{"type":"integer","format":"int64","description":"Decimal value encoded on the wire as an integer scaled by the asset's exponent: `encoded = real × 10^exponent`. E.g. for a bond denominated in EUR (exponent=2), a coupon payment of `123.45` is encoded as `12345`, and a nominal value of `1000.00` is encoded as `100000`."},"EquityDistributionDto":{"type":"object","properties":{"id":{"type":"string","description":"Equity distribution UUID identifier, unique in scope of this node","format":"uuid"},"equityId":{"type":"string","description":"Unique UUID of the equity in scope of this gateway","format":"uuid"},"accountAddress":{"type":"string","description":"Equity`s destination address corresponding to the investor account address"},"amount":{"format":"int64","description":"Amount of equity sent to the provided investor.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]},"reference":{"type":"string","description":"Reference to a document or corporate action number, etc. - anything that could help relate distribution actions with other context"},"recordedAt":{"type":"string","description":"Day when the action was documented to be executed. This is not necessarily the day when the equity is actually distributed to the investor."},"status":{"description":"Status of equity distribution action","allOf":[{"$ref":"#/components/schemas/EquityDistributionStatus"}]}},"required":["id","equityId","accountAddress","amount","reference","recordedAt","status"]},"EquityDistributionStatus":{"type":"string","enum":["successful","failed"],"description":"Status of equity distribution action"}}}}
```

## GET /equities/{equityId}/accounts

> Retrieve a list of accounts with balance for specified equity.

```json
{"openapi":"3.1.0","info":{"title":"Axiology TSS Broker Node API","version":"0.0.1"},"paths":{"/equities/{equityId}/accounts":{"get":{"description":"Retrieve a list of accounts with balance for specified equity.","operationId":"getEquityAccounts","parameters":[{"name":"equityId","required":true,"in":"path","description":"Equity UUID identifier, global in scope of TSS","schema":{"format":"uuid","type":"string"}},{"name":"query","required":false,"in":"query","style":"deepObject","explode":true,"schema":{"$ref":"#/components/schemas/QueryEquityAccountDto"}},{"name":"filter","required":false,"in":"query","style":"deepObject","explode":true,"schema":{"$ref":"#/components/schemas/FilterEquityAccountDto"}},{"name":"pagination","required":false,"in":"query","style":"deepObject","explode":true,"schema":{"$ref":"#/components/schemas/PaginationRequestDto"}},{"name":"order","required":false,"in":"query","content":{"application/json":{"schema":{"type":"array","uniqueItems":true,"items":{"type":"object","oneOf":[{"properties":{"amount":{"type":"string","enum":["asc","desc"]}},"required":["amount"]}]}}}},"description":"Array of fields and directions to order. Supported fields: amount"}],"responses":{"200":{"description":"Successfully retrieved a list of items.","content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/PaginationResponseDto"},"items":{"type":"array","items":{"$ref":"#/components/schemas/EquityAccountBalanceDto"}}},"required":["pagination","items"]}}}}},"summary":"","tags":["Equities"]}}},"components":{"schemas":{"QueryEquityAccountDto":{"type":"object","properties":{"heldAt":{"format":"date-time","type":"string","description":"Get equity accounts by the end day they were held. (skip the property for current holdings)"}}},"FilterEquityAccountDto":{"type":"object","properties":{"accountAddress":{"description":"Filter accounts by account address","oneOf":[{"type":"array","items":{"description":"Account address","type":"string","format":"xrp-address","pattern":"r[0-9a-zA-Z]{24,34}"},"minItems":1},{"type":"string","description":"Partial account address"}]},"amount":{"description":"Filter accounts by amount from number or between two numbers","oneOf":[{"type":"array","items":{"type":"integer","format":"int64"},"minItems":1,"maxItems":2},{"type":"integer","format":"int64"}]}}},"PaginationRequestDto":{"type":"object","properties":{"size":{"type":"number","minimum":1,"default":10},"page":{"type":"number","minimum":1,"default":1}}},"PaginationResponseDto":{"type":"object","properties":{"size":{"type":"number","minimum":1,"default":10},"page":{"type":"number","minimum":1,"default":1},"totalItems":{"type":"number","description":"Total items count"},"totalPages":{"type":"number","description":"Total pages count"}},"required":["totalItems","totalPages"]},"EquityAccountBalanceDto":{"type":"object","properties":{"account":{"description":"Account details","allOf":[{"$ref":"#/components/schemas/AccountDto"}]},"amount":{"format":"int64","description":"Equity amount held by the account.\n\nScaled as `ExponentScaledDecimal`.","allOf":[{"$ref":"#/components/schemas/ExponentScaledDecimal"}]}},"required":["account","amount"]},"AccountDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"Created date"},"updatedAt":{"format":"date-time","type":"string","description":"Updated date"},"nodeId":{"type":"string","description":"Unique UUID of the node that manages this account","format":"uuid"},"address":{"type":"string","description":"Account address","format":"xrp-address","pattern":"r[0-9a-zA-Z]{24,34}"},"type":{"description":"Type of account","allOf":[{"$ref":"#/components/schemas/AccountType"}]},"institutionSectorCode":{"description":"ESA 2010 / ECB institutional sector classification code used for statistical and regulatory reporting. This describes sector, not legal form.","nullable":true,"allOf":[{"$ref":"#/components/schemas/InstitutionSectorCode"}]},"walletType":{"description":"Indicates that funds are owned by either broker or client","nullable":true,"allOf":[{"$ref":"#/components/schemas/WalletType"}]},"status":{"description":"**Status of the account:**\n- `active` - account is allowed to interact with the system\n- `frozen` - no assets can be moved around\n- `deleted` - no further actions can be done","allOf":[{"$ref":"#/components/schemas/AccountStatus"}]},"openedAt":{"format":"date-time","type":"string","description":"Opened date"}},"required":["createdAt","updatedAt","nodeId","address","type","institutionSectorCode","walletType","status","openedAt"]},"AccountType":{"type":"string","enum":["broker","emi","funding","investor","issuer","issuing","node","operational","operator"],"description":"Type of account"},"InstitutionSectorCode":{"type":"string","enum":["S.11","S.121","S.122","S.123","S.124","S.125","S.126","S.127","S.128","S.129","S.13","S.1311","S.1312","S.1313","S.1314","S.14","S.15"],"description":"ESA 2010 / ECB institutional sector classification code used for statistical and regulatory reporting. This describes sector, not legal form."},"WalletType":{"type":"string","enum":["broker-own","client-individual"],"description":"Indicates that funds are owned by either broker or client"},"AccountStatus":{"type":"string","enum":["active","frozen","deleted"],"description":"**Status of the account:**\n- `active` - account is allowed to interact with the system\n- `frozen` - no assets can be moved around\n- `deleted` - no further actions can be done"},"ExponentScaledDecimal":{"type":"integer","format":"int64","description":"Decimal value encoded on the wire as an integer scaled by the asset's exponent: `encoded = real × 10^exponent`. E.g. for a bond denominated in EUR (exponent=2), a coupon payment of `123.45` is encoded as `12345`, and a nominal value of `1000.00` is encoded as `100000`."}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://axiology.gitbook.io/axiology-docs/rest-api/equities.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.