Address Book

Address Book

Save recipient addresses in groups so you can reuse them. The address book does not send funds. Create Payout still takes the recipient list directly; it does not accept a group_id.

chain_type is chosen when you create the group and cannot be changed:

chain_type	Address shape
evm	0x plus 40 hex characters.
solana	Base58 public key, 32 bytes after decode.
tron	T plus 33 Base58 characters.

Send the stored value, or an alias: eth / ethereum for evm, sol for solana, and trx for tron. Matching is case-insensitive. The group stores the canonical value.

Limits: 20 groups per merchant, 100 addresses per group, group name up to 50 characters, note up to 100 characters. Create and append skip duplicate addresses in the same group (case-insensitive) and report them in skipped_addresses. Updating one entry to an address that already exists in the group returns 90134 instead of skipping.

All requests must be authenticated with your API Key. Do not send merchant_id. Identifiers go in the query string or JSON body, never in the path.

Base URL

https://pay-openapi.morph.network/pro/merchant/payout/v1

Endpoint paths in this page are relative to that base URL.

Response envelope

Every response is wrapped in a common envelope:

{
  "error_code": 0,
  "msg": "success",
  "data": {},
  "trace": "..."
}

note

Business success or failure is determined by error_code (error_code == 0 means success), not by the HTTP status code alone. See the Error Codes reference for the full list.

List groups

GET /address-book/groups

Returns every group for the authenticated merchant. The list does not include addresses. Use Get group for those.

Success response

{
  "error_code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "group_id": "ab_...",
        "name": "ops",
        "chain_type": "evm",
        "entry_count": 2
      }
    ]
  },
  "trace": "..."
}

Create group

POST /address-book/groups

Request fields

Field	Type	Required	Description
name	string	Yes	Group name, 1–50 characters.
chain_type	string	Yes	evm, solana, or tron, or an alias (eth / ethereum, sol, trx). Case-insensitive. Stored as the canonical family and immutable after create. Empty or whitespace-only returns 90000 and does not create a group. Any other value returns 90111.
entries	object[]	Yes	At least one address. An empty array returns 90000.
entries[].address	string	Yes	Must match chain_type. The first invalid address returns 90133.
entries[].note	string	No	Up to 100 characters.

Request example

{
  "name": "ops",
  "chain_type": "evm",
  "entries": [
    { "address": "0xAbCd000000000000000000000000000000000001", "note": "first" },
    { "address": "0xabcd000000000000000000000000000000000001", "note": "dup" }
  ]
}

The second row is the same address with different casing, so it is skipped.

Success response

{
  "error_code": 0,
  "msg": "success",
  "data": {
    "group": {
      "group_id": "ab_...",
      "name": "ops",
      "chain_type": "evm",
      "entry_count": 1,
      "entries": [
        {
          "entry_id": "abe_...",
          "address": "0xabcd000000000000000000000000000000000001",
          "note": "first"
        }
      ]
    },
    "skipped_count": 1,
    "skipped_addresses": ["0xabcd000000000000000000000000000000000001"]
  },
  "trace": "..."
}

A 21st group returns 90129. More than 100 unique addresses returns 90130.

Get group

GET /address-book/groups/detail?group_id=<group_id>

Query fields

Field	Type	Required	Description
group_id	string	Yes	Group id. Missing returns 90000. Unknown returns 90131.

Success response

data is the group object from Create group: group_id, name, chain_type, entry_count, and entries.

Rename group

PUT /address-book/groups/rename

Changes the name only. chain_type and entries stay as they are.

Request fields

Field	Type	Required	Description
group_id	string	Yes	Group id.
name	string	Yes	New name, 1–50 characters.

Request example

{
  "group_id": "ab_...",
  "name": "ops-renamed"
}

Success is error_code == 0 with data null. An unknown group returns 90131.

Delete group

DELETE /address-book/groups?group_id=<group_id>

Deletes the group and every entry in it. An unknown group returns 90131. A later Get group for the same id also returns 90131.

Append entries

POST /address-book/entries

Adds addresses to an existing group. Duplicates of addresses already in the group are skipped. The new address must match the group's chain_type.

Request fields

Field	Type	Required	Description
group_id	string	Yes	Group id.
entries	object[]	Yes	Addresses to add.
entries[].address	string	Yes	Must match the group's chain_type.
entries[].note	string	No	Up to 100 characters.

Request example

{
  "group_id": "ab_...",
  "entries": [
    { "address": "0xAbCd000000000000000000000000000000000002", "note": "second" }
  ]
}

Success response

{
  "error_code": 0,
  "msg": "success",
  "data": {
    "group": {
      "group_id": "ab_...",
      "name": "ops",
      "chain_type": "evm",
      "entry_count": 2,
      "entries": [
        {
          "entry_id": "abe_...",
          "address": "0xabcd000000000000000000000000000000000001",
          "note": "first"
        },
        {
          "entry_id": "abe_...",
          "address": "0xabcd000000000000000000000000000000000002",
          "note": "second"
        }
      ]
    },
    "added_count": 1,
    "skipped_count": 0,
    "skipped_addresses": []
  },
  "trace": "..."
}

group is the full detail after the append. Crossing 100 addresses returns 90130 and nothing is added.

Update entry

PUT /address-book/entries

Replaces one entry's address and note. A collision with another entry in the same group returns 90134 and leaves the entry unchanged. An unknown entry_id returns 90132.

Request fields

Field	Type	Required	Description
entry_id	string	Yes	Entry id from the group detail.
address	string	Yes	New address. Must match the group's chain_type.
note	string	No	New note. Omit or send "" to clear.

Request example

{
  "entry_id": "abe_...",
  "address": "0xAbCd000000000000000000000000000000000001",
  "note": "renamed-note"
}

Success is error_code == 0 with data null.

Delete entry

DELETE /address-book/entries?entry_id=<entry_id>

Field	Type	Required	Description
entry_id	string	Yes	Entry id. Missing returns 90000. Unknown returns 90132.

The group remains. Deleting the last entry leaves entry_count at 0.