# Transfer Position External API

Use API credentials to view and manage instruments.

Version: 1.0.0

## Servers

```
https://optimalapi-ext.apx.com/transfer/v1
```

```
https://optimalapi-uat-ext.apx.com/transfer/v1
```

## Security

### JWT

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Transfer Position External API](https://developer.xpansiv.com/_bundle/openapi/optimal-v1/optimal.transferposition.v1.openapi.yaml)

## transferbatch-v1

Initiate a transfer request (between subaccounts or another account holder), view or act upon pending transfers, as well as view historical transfer details.

### Initiate counterparty transfer

 - [POST /api/ledger/{ledgerIdentifier}/transfer](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/transferbatch-v1/initiateaccounttransfers.md): Initiate transfer will propose the transaction to the counterparty, after which the counterparty will be prompted to act on the proposal.

### Act on a proposed transfer

 - [POST /api/ledger/{ledgerIdentifier}/transferBatch/open/action](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/transferbatch-v1/acknowledgetransferbatches.md): Actions include accept, reject or withdrawal of a proposed transfer, using the transfer batch identifier.

### Retrieve transfer request details

 - [POST /api/ledger/{ledgerIdentifier}/transferBatch/byIdentifier](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/transferbatch-v1/gettransferbatchesbyidentifier.md): View the details behind a transfer request, using the transfer batch identifier.

### Transfer holdings between subaccounts

 - [POST /api/ledger/{ledgerIdentifier}/transfer/subaccount](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/transferbatch-v1/initiatesubaccounttransfers.md): Transfers holdings between active subaccounts, within the same account.

### Retrieve pending transfer requests

 - [GET /api/ledger/{ledgerIdentifier}/transferBatch/open](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/transferbatch-v1/getopentransferbatches.md): Retrieve list of currently pending transfers.

## retirementbatch-v1

View or submit a retirement request, or redemption claim, on instrument(s).

### Retrieve retirement request details

 - [POST /api/ledger/{ledgerIdentifier}/retirementBatch/byIdentifier](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/retirementbatch-v1/getretirementbatchesbyidentifier.md): View retirement details using the retirement batch identifier

### Initiate a retirement request

 - [POST /api/ledger/{ledgerIdentifier}/retire](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/retirementbatch-v1/initiateretirements.md): Retire, or claim, instruments against an obligation

## ledger-v1

View an Account's current and historical instrument details

### Retrieve instrument details at origination

 - [POST /api/ledger/{ledgerIdentifier}/issuance/byIdentifier](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/ledger-v1/getissuancebatchbyidentifier.md): View instrument details at origination using the issuance identifier.

### Retrieve available ledgers

 - [GET /api/ledger](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/ledger-v1/getledgers.md): View the list of available ledgers by registry

### Retrieve account holdings

 - [GET /api/ledger/{ledgerIdentifier}/holding](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/ledger-v1/getledgerholdings.md): View current instruments by ledger, using the ledger identifier.

### Retrieve account transfers and retirements

 - [GET /api/ledger/{ledgerIdentifier}/history](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/ledger-v1/getledgerhistory.md): View your account's ledger history, such as account-to-account transfers and retirements.

### Retrieves list of counterparties

 - [GET /api/ledger/{ledgerIdentifier}/account](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/ledger-v1/getledgeraccounts.md): View counterparties for account-to-account transfers. Counterparties are returned by Program Ledger.

## subaccount-v1

View or create subaccounts. Use subaccounts to organize your account’s instruments. All accounts have a "Default" subaccount, where all new issuances and incoming transfers will be deposited. Subaccounts may also be used to delegate instrument management to an authorized third party.

### Retrieve sub-accounts

 - [GET /api/ledger/{ledgerIdentifier}/subaccount](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/subaccount-v1/getsubaccounts.md): Retrieve available subaccounts by account.

### Create sub-account

 - [POST /api/ledger/{ledgerIdentifier}/subaccount](https://developer.xpansiv.com/openapi/optimal-v1/optimal.transferposition.v1.openapi/subaccount-v1/createsubaccount.md): Create a new subaccount to organize your account’s instruments or to delegate transaction authority to an authorized third party. All accounts have a "Default" subaccount.