Skip to content
Optimal Outcomes
/
/
/
Retrieve instrument detai...

Transfer Position External API (1.0.0)

Use API credentials to view and manage instruments.

Download OpenAPI description
optimal.transferposition.v1.openapi.json
optimal.transferposition.v1.openapi.yaml
Languages
Servers
https://optimalapi-ext.apx.com/transfer/v1/
https://optimalapi-uat-ext.apx.com/transfer/v1/

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.

Operations

retirementbatch-v1

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

Operations

ledger-v1

View an Account's current and historical instrument details

Operations

Retrieve instrument details at origination

Request

View instrument details at origination using the issuance identifier.

Security
JWT
Path
ledgerIdentifierstring(uuid)required

Ledger identifier, can be found using /api/ledger endpoint

Example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
Bodyapplication/jsonrequired

Populated IssuanceRetrieveByIdentifierRequest

onBehalfOfSrcAcctIdstring

If permitted, allows the caller to retrieve issuances on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.

issuanceIdentifiersArray of stringsunique

Collection of issuance identifiers for the issuances to retrieve.

curl -i -X POST \
  https://optimalapi-ext.apx.com/transfer/v1/api/ledger/4b7375e9-79b0-4b8b-a89e-a21607f0239f/issuance/byIdentifier \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "onBehalfOfSrcAcctId": "string",
    "issuanceIdentifiers": [
      "string"
    ]
  }'

Responses

success

Bodyapplication/json
issuancesArray of objects(Issuance)
Response
application/json
{
  "issuances": [
    { … }
  ]
}

Retrieve available ledgers

Request

View the list of available ledgers by registry

Security
JWT
curl -i -X GET \
  https://optimalapi-ext.apx.com/transfer/v1/api/ledger \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Ledgers retrieved

Bodyapplication/json
ownershipLedgersArray of objects(OwnershipLedger)

A list of available ownership ledgers.

Response
application/json
{
  "ownershipLedgers": [
    { … }
  ]
}

Retrieve account holdings

Request

View current instruments by ledger, using the ledger identifier.

Security
JWT
Path
ledgerIdentifierstringrequired

Ledger identifier, can be found using /api/ledger endpoint

Example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
Query
assetboolean

If true, requests asset holdings, otherwise requests liability holdings.

Example: asset=true
onBehalfOfSrcAcctIdstring

If permitted, allows the caller to request holdings for another account holder, identifying that account holder by their system-assigned srcAcctId.

Example: onBehalfOfSrcAcctId=4b7375e9-79b0-4b8b-a89e-a21607f0239f
transferTypeCodestring

If specified, only holdings that qualify for the specified transfer type will be returned

Example: transferTypeCode=RET
$skipinteger(int32)

Number of records to skip

$topinteger(int32)

Maximum number of records to return

$filterstring

OData-like filter expression

$applystring

OData-like apply expression with groupby and aggregate only

$orderbystring

Comma-separated list of columns for sorting

$countboolean

Whether to include the count of records with the result

curl -i -X GET \
  'https://optimalapi-ext.apx.com/transfer/v1/api/ledger/4b7375e9-79b0-4b8b-a89e-a21607f0239f/holding?asset=true&onBehalfOfSrcAcctId=4b7375e9-79b0-4b8b-a89e-a21607f0239f&transferTypeCode=RET&%24skip=0&%24top=0&%24filter=string&%24apply=string&%24orderby=string&%24count=true' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Holdings retrieved

Bodyapplication/json
@countinteger(int32)

The total number of results (only present if requested)

valueArray of objects(Holding)required

Rows of information

value[].​identifierstring

The holding's system-assigned identifier.

value[].​resourceProgramAssignedIdentifierstring

The associated resource's program assigned identifier.

Example: "GHG1021"
value[].​holdingStatusobject(ReferenceDatum)

A reference datum data object

Example: "GOC"
value[].​programPeriodBeginInclusivestring(date-time)

Start of program period (vintage) associated to the holding record's issuance.

Example: "2022-01-01T00:00:00-05:00"
value[].​programPeriodEndExclusivestring(date-time)

End of program period (vintage) associated to the holding record's issuance.

Example: "2023-01-01T00:00:00-05:00"
value[].​timeOfProductionBeginInclusivestring(date-time)

Start of production period associated to the holding's issuance

Example: "2022-01-01T00:00:00-05:00"
value[].​timeOfProductionEndExclusivestring(date-time)

End of production period associated to the holding's issuance

Example: "2023-01-01T00:00:00-05:00"
value[].​serialNumberstring

The holding record's serial number.

Example: "APXOPCAR-GOC-GHG1021-US-2022--46-5701-6700"
value[].​quantitynumber

The quantity of the holding record.

Example: 1000
value[].​programVersionsArray of objects(ProgramVersion)

Associated programs and their versions.

value[].​protocolVersionsArray of objects(ProtocolVersion)

Associated protocols and their versions.

value[].​resourceInputTypeCodesArray of strings

A list of resource input types associated with the holding record's issuance.

value[].​resourceOutputTypeCodesArray of strings

A list of resource output types associated with the holding record's issuance.

Example: "CARBON_REDUCTION"
value[].​subaccountIdentifierstring

The system-assigned identifier for the subaccount.

Example: "5FF7ABAA-095D-11EF-B304-AA080FC10FFA"
value[].​subaccountNamestring

Subaccount name, as inputted by subaccount owner.

Example: "My Linked Holdings"
value[].​subaccountNumberstring

Subaccount Id displayed on the Optimal Outcomes platform's UI.

Example: "10033"
value[].​programCertificationGroupCodestring

The issuing program certification group of the holding record.

Example: "NONAFOLU_GHG_MEASUREMENT_PROGRAM"
value[].​upnstring

Xpansiv Connect Universal Project Number (UPN) for Resource associated to the holding's issuance, if assigned.

Example: "0999F5B4"
value[].​einstring

Xpansiv Connect Environmental Instrument Number (EIN), if assigned.

Example: "1246AFA3E2"
value[].​einDescriptionstring

Xpansiv Connect Environmental Instrument Number (EIN) details, if assigned

Example: "VCU-20120101-20121231-EDEM-3267-ZMB"
value[].​shadowedLedgerNamestring

If shadowing = true, the external ledger's name.

Example: "Verra"
value[].​managingExternalPlatformNamestring

If the holding is held in an external subaccount, the name of the managing external platform associated with the external subaccount.

Example: "Xpansiv Connect"
value[].​certificateTypeobject(ReferenceDatum)

A reference datum data object

Example: "GOC"
Response
application/json
{
  "@count": 0,
  "value": [
    { … }
  ]
}

Retrieve account transfers and retirements

Request

View your account's ledger history, such as account-to-account transfers and retirements.

Security
JWT
Path
ledgerIdentifierstring(uuid)required

Ledger identifier, can be found using /api/ledger endpoint

Example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
Query
onBehalfOfSrcAcctIdstring

If permitted, allows the caller to request transfer history on behalf of another account holder, identifying that account holder by their system-assigned srcAcctId.

Example: onBehalfOfSrcAcctId=4b7375e9-79b0-4b8b-a89e-a21607f0239f
$skipinteger(int32)
$topinteger(int32)
$filterstring
$applystring
$orderbystring
$countboolean
curl -i -X GET \
  'https://optimalapi-ext.apx.com/transfer/v1/api/ledger/4b7375e9-79b0-4b8b-a89e-a21607f0239f/history?onBehalfOfSrcAcctId=4b7375e9-79b0-4b8b-a89e-a21607f0239f&%24skip=0&%24top=0&%24filter=string&%24apply=string&%24orderby=string&%24count=true' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

transfer batches retrieved

Bodyapplication/json
ledgerHistoryRecordsArray of objects(LedgerHistory)

A collection of ledger history entries.

Response
application/json
{
  "ledgerHistoryRecords": [
    { … }
  ]
}

Retrieves list of counterparties

Request

View counterparties for account-to-account transfers. Counterparties are returned by Program Ledger.

Security
JWT
Path
ledgerIdentifierstringrequired

Ledger identifier, can be found using /api/ledger endpoint

Example: 4b7375e9-79b0-4b8b-a89e-a21607f0239f
curl -i -X GET \
  https://optimalapi-ext.apx.com/transfer/v1/api/ledger/4b7375e9-79b0-4b8b-a89e-a21607f0239f/account \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Accounts retrieved

Bodyapplication/json
ledgerAccountsArray of objects(LedgerAccount)

A list of accounts related to the specified ownership ledger.

Response
application/json
{
  "ledgerAccounts": [
    { … }
  ]
}

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.

Operations