# Add a wallet address

Adds an external wallet owned by the selected client to the client's address book. Partner-owned and third-party wallets are not allowed.
The wallet starts in `PENDING_REVIEW`. After it becomes `ACTIVE`, it may fund the client's deposits and receive the client's withdrawals. The `destination.activated` webhook reports this change.

Product: Client Trade API
API reference version: 0.3.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/trade-api/0.3.0.yaml
Canonical page: https://docs.axiym.io/trade-api/api-reference/0.3.0/address-book/createWalletEntry

[Complete reference with related definitions](/trade-api/api-reference/0.3.0/address-book/createWalletEntry.full.md)

## POST /clients/{clientId}/address-book/wallets

## Servers

```json
[
  {
    "url": "https://partner-api.sandbox.axiym.io/api/v1",
    "description": "Sandbox"
  },
  {
    "url": "https://partner-api.axiym.io/api/v1",
    "description": "Production"
  }
]
```

## Authentication

```json
{
  "security": [
    {
      "Default": []
    }
  ],
  "securitySchemes": {
    "Default": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
}
```

## Parameters

### path: clientId

```json
{
  "name": "clientId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f"
    ]
  },
  "description": "Client identifier (UUID) assigned when an onboarding case is created. It identifies the onboarding case and, once active, the client's Client Trade API resources. The client must belong to your partnership; anyone else's id returns 404."
}
```

### header: X-Request-Id

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support.\n",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### header: Idempotency-Key

```json
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "description": "A unique key that makes a funds-moving request safe to retry. Reusing the key returns the original result instead of creating a duplicate. A UUID is recommended.",
  "schema": {
    "type": "string",
    "maxLength": 255,
    "examples": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
}
```

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/WalletDestinationRequest"
      }
    }
  }
}
```

## Responses

### 201

```json
{
  "description": "Wallet address added to the client's address book and awaiting review.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AddressBookEntry"
      },
      "examples": {
        "Wallet address": {
          "summary": "Wallet address",
          "value": {
            "destinationId": "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c",
            "status": "PENDING_REVIEW",
            "currency": "USDT",
            "walletAddress": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL",
            "network": "TRON",
            "createdAt": "2026-06-12T14:05:00Z"
          }
        }
      }
    }
  }
}
```

### 400

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 401

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 403

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 422

```json
{
  "description": "The request failed validation or a business rule. Validation failures return `errors` keyed by request field. Business rejections return `errors: null` and explain the reason in `message`.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "`Invalid Parameters` for validation failures; the rejection reason otherwise."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ValidationFieldErrors"
            }
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Flat field errors": {
          "summary": "Flat field errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalEntityName": [
                {
                  "code": "length",
                  "message": null,
                  "params": {
                    "value": "",
                    "min": 1
                  }
                }
              ],
              "currency": [
                {
                  "code": "invalid_currency",
                  "message": null,
                  "params": {
                    "value": "ZZZ"
                  }
                }
              ]
            }
          }
        },
        "Nested struct errors": {
          "summary": "Nested struct errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalAddress": {
                "country": [
                  {
                    "code": "invalid_country",
                    "message": null,
                    "params": {
                      "value": "INVALID"
                    }
                  }
                ],
                "postalCode": [
                  {
                    "code": "length",
                    "message": null,
                    "params": {
                      "value": "",
                      "min": 1
                    }
                  }
                ]
              }
            }
          }
        },
        "List item errors": {
          "summary": "List item errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "authorizedDirectors": {
                "0": {
                  "firstName": [
                    {
                      "code": "length",
                      "message": null,
                      "params": {
                        "value": "",
                        "min": 1
                      }
                    }
                  ],
                  "email": [
                    {
                      "code": "email",
                      "message": null,
                      "params": {
                        "value": "not-an-email"
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "Custom validator": {
          "summary": "Custom validator",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "disbursementAccount": [
                {
                  "code": "disbursement_account_required",
                  "message": null,
                  "params": {
                    "value": null
                  }
                }
              ]
            }
          }
        },
        "Business rejection": {
          "summary": "Business rejection",
          "value": {
            "code": 422,
            "message": "Documents Not Accepted",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 500

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

## Operation metadata

```json
{
  "tags": [
    "Address Book"
  ],
  "operationId": "createWalletEntry"
}
```

## Referenced schemas

Fetch the relevant schema to inspect its fields, constraints and related types.

- [`#/components/schemas/WalletDestinationRequest`](/trade-api/api-reference/0.3.0/schemas/WalletDestinationRequest.md)
- [`#/components/schemas/AddressBookEntry`](/trade-api/api-reference/0.3.0/schemas/AddressBookEntry.md)
- [`#/components/schemas/ValidationFieldErrors`](/trade-api/api-reference/0.3.0/schemas/ValidationFieldErrors.md)