Manage endpoints

Use this page to manage endpoint address book entries. For the concept, see Endpoints.

Endpoint changes use the standard intent flow. For signing, approval, and status checks, see Manage intents and approvals, Sign intents, and Check updates.

Use endpoint API read operations to list and get endpoint records. Use endpoint intent payloads to create, update, lock, and unlock endpoint records. Submit endpoint intents to Propose an intent. Use Perform a dry run before you sign high-risk or unfamiliar payloads.

You can register a ledger address or, if the ledger supports smart contracts, a smart contract address as an endpoint.

If this is a smart contract endpoint, you can provide the contract application binary interface (ABI) data when you register the endpoint.

To register an endpoint:

1. Navigate to Endpoints.
2. Select Create an endpoint.
3. Enter the details of the endpoint, such as the name and description.
4. Select the ledger.
5. Enter the endpoint address.
6. If the endpoint address is a smart contract address, enter smart contract ABI details in one of the following ways:
   • Enter the ABI in JSON format.
   • Upload the ABI in a file.
7. Enter the trust score as a number from 0 to 100.
8. Select Submit for Approval and sign the operation with the app.

You can register a ledger address or, if the ledger supports smart contracts, a smart contract address as an endpoint.

If this is a smart contract endpoint, you can provide the contract application binary interface (ABI) data when you create the endpoint.

Before you register an endpoint, prepare:

Create an endpoint by submitting a v0_CreateEndpoint intent.

{
  "payload": {
    "id": "c3ddaca1-07d8-437d-803b-bfdef7833aa4",
    "address": "0x258aE861829FB6B33e7528308cA2938638590F34",
    "trustScore": 50,
    "ledgerId": "ethereum-testnet",
    "alias": "Ethereum Testnet",
    "lock": "Unlocked",
    "description": "Ethereum testnet wallet",
    "customProperties": {},
    "type": "v0_CreateEndpoint"
  }
}

{
  "payload": {
    "id": "b445e1d1-41fe-468a-a600-1b9ad7b057e1",
    "address": "0xb2f701a94d864b131fd47c9cf4563e6298afdbfc",
    "trustScore": 50,
    "ledgerId": "ethereum-testnet",
    "parameters": {
      "ABI": "<ABI_JSON_STRING>",
      "type": "Ethereum"
    },
    "alias": "MTT Smart Contract",
    "lock": "Unlocked",
    "description": "MTT token contract",
    "customProperties": {},
    "type": "v0_CreateEndpoint"
  }
}

Fields of the payload block to note are:

Dry run before submitting:

curl -X POST "${CUSTODY_API_URL}/v1/intents/dry-run" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @create-endpoint-intent.json

Submit the signed intent:

curl -X POST "${CUSTODY_API_URL}/v1/intents" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @signed-create-endpoint-intent.json

To view endpoints in the UI:

1. Navigate to Endpoints.
2. Review the endpoint list.
3. Open an endpoint to review its details.

The endpoint list shows known destinations in the selected domain.

To view endpoint details:

1. If you do not know the endpoint ID, retrieve a list of endpoints in the domain with List endpoints. You can filter the list by ledger with the ledgerId query parameter.
2. Retrieve endpoint details with Get endpoint details, using the endpoint ID from step 1.

Use List endpoints query parameters to narrow or sort endpoint lists:

The API returns trusted endpoint objects. Inspect the data object for endpoint details.

Depending on the endpoint type, data includes:

• Endpoints that are ledger addresses do not include ABI data in the parameters field.
• Endpoints that are associated with a smart contract address have ABI data in the parameters field in JSON format.

The data object also includes domainId, metadata, lock, and trustScore so you can confirm ownership, revision, availability, and policy inputs before you use the endpoint in a transaction order. The trusted endpoint envelope also includes signature and signingKey.

You can update the following details of an endpoint:

• Name and description.
• Address.
• Trust score.
• Custom properties.

You cannot update the ledger.

To update an endpoint:

1. Navigate to Endpoints.
2. At the end of the endpoint row, open the contextual menu and select Edit.
3. Update the details of the endpoint.
4. Select Submit for Approval and sign the operation with the app.

You can update general details of an endpoint such as the address and the trust score. For a smart contract endpoint, you can also update the application binary interface (ABI) data.

Endpoint updates use a v0_UpdateEndpoint intent. Submit the update through the standard intent flow, then check the endpoint after execution.

Do not include ledgerId in endpoint update payloads. The API specification marks ledgerId as deprecated for v0_UpdateEndpoint, and you cannot update the ledger in the UI.

Omit parameters unless you update ABI data for a smart contract endpoint.

{
  "payload": {
    "reference": {
      "id": "c3ddaca1-07d8-437d-803b-bfdef7833aa4",
      "revision": 2
    },
    "address": "0x258aE861829FB6B33e7528308cA2938638590F34",
    "trustScore": 75,
    "alias": "Ethereum treasury endpoint",
    "description": "Updated Ethereum treasury destination",
    "customProperties": {},
    "type": "v0_UpdateEndpoint"
  }
}

For a smart contract endpoint, include the parameters object with the updated ABI data:

{
  "parameters": {
    "ABI": "<ABI_JSON_STRING>",
    "type": "Ethereum"
  }
}

Endpoint lock-state changes use the standard intent flow.

Submit a lock intent with the current endpoint reference:

{
  "payload": {
    "reference": {
      "id": "c3ddaca1-07d8-437d-803b-bfdef7833aa4",
      "revision": 2
    },
    "type": "v0_LockEndpoint"
  }
}

Use v0_UnlockEndpoint with the same reference shape to re-enable the endpoint.

Before submitting an endpoint intent:

• Confirm the endpoint is in the correct domain.
• Confirm the ledger and address are correct.
• Confirm the trust score matches your policy model.
• Confirm whether the endpoint represents a smart contract and needs ABI data.
• Dry run the payload when using the API.
• Verify the executed change by viewing the endpoint.