---
updatedAt: 2026-09-07T10:30:07.000Z
agentTools:
  projectIndex: https://docs.itispay.com/llms.txt
---

# Create a deposit address

Generate a reusable cryptocurrency deposit address for the authenticated project.

The API creates a local deposit, generates a `uid`, allocates a blockchain address, and returns the stored deposit. Incoming payments to this address are credited to the matching currency account. Only one currency is allowed per request.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Cryptocurrency Invoice API",
    "version": "1.1.0",
    "description": "REST API for generating and managing cryptocurrency invoices with support for multiple transactions per invoice",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "contact": {
      "name": "API Support",
      "email": "api@itispay.com",
      "url": "https://itispay.com/support"
    }
  },
  "servers": [
    {
      "url": "https://api.itispay.com",
      "description": "Production server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Api-key",
        "description": "To obtain an API key, you must register on https://itispay.com. After successful registration, you can access your API key through your account dashboard. Provide your API key in the Api-key header as: Api-key: YOUR_API_KEY"
      }
    },
    "schemas": {
      "ErrorDetail": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Name of the field that has the error"
          },
          "message": {
            "type": "string",
            "description": "Specific error message for the field"
          }
        }
      },
      "ErrorContent": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code"
          },
          "message": {
            "type": "string",
            "description": "Main error message"
          },
          "details": {
            "type": "array",
            "description": "Array of field-specific error details (optional, empty for non-validation errors)",
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorContent"
          }
        }
      },
      "CreateDepositRequest": {
        "type": "object",
        "required": [
          "currency"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "description": "Cryptocurrency code for the deposit address. Only one currency is allowed per request.",
            "example": "USDT_TRX"
          },
          "label": {
            "type": "string",
            "maxLength": 255,
            "description": "Optional human-readable note for the deposit.",
            "example": "hot wallet"
          },
          "callback_url": {
            "type": "string",
            "maxLength": 2048,
            "description": "Optional URL that receives deposit payment callbacks.",
            "example": "https://merchant.example/callbacks/deposits"
          }
        }
      },
      "Deposit": {
        "type": "object",
        "properties": {
          "uid": {
            "type": "string",
            "format": "uuid",
            "description": "Generated deposit identifier returned to the merchant.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "currency": {
            "type": "string",
            "example": "USDT_TRX"
          },
          "address": {
            "type": "string",
            "description": "Blockchain deposit address.",
            "example": "TXYZopYRdj2D9XRtbG411XWR3yWqed2dq"
          },
          "label": {
            "type": "string",
            "description": "Optional human-readable note.",
            "example": "hot wallet"
          },
          "callback_url": {
            "type": "string",
            "description": "Optional URL that receives deposit payment callbacks.",
            "example": "https://merchant.example/callbacks/deposits"
          },
          "network_name": {
            "type": "string",
            "example": "Tron"
          },
          "network_type": {
            "type": "string",
            "example": "TRC-20"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "active",
              "failed"
            ],
            "example": "active"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Crypto deposit/withdraw",
      "description": "Reusable cryptocurrency deposit addresses, custody wallet hashes, and crypto withdrawals."
    }
  ],
  "paths": {
    "/api/v1/deposit": {
      "post": {
        "summary": "Create a deposit address",
        "description": "Generate a reusable cryptocurrency deposit address for the authenticated project.\n\nThe API creates a local deposit, generates a `uid`, allocates a blockchain address, and returns the stored deposit. Incoming payments to this address are credited to the matching currency account. Only one currency is allowed per request.",
        "operationId": "createDeposit",
        "tags": [
          "Crypto deposit/withdraw"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDepositRequest"
              },
              "examples": {
                "usdt_deposit": {
                  "summary": "USDT TRC-20 deposit",
                  "value": {
                    "currency": "USDT_TRX",
                    "label": "hot wallet"
                  }
                },
                "btc_deposit": {
                  "summary": "Bitcoin deposit",
                  "value": {
                    "currency": "BTC"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Deposit created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Deposit"
                },
                "example": {
                  "uid": "550e8400-e29b-41d4-a716-446655440000",
                  "currency": "USDT_TRX",
                  "address": "TXYZopYRdj2D9XRtbG411XWR3yWqed2dq",
                  "label": "hot wallet",
                  "network_name": "Tron",
                  "network_type": "TRC-20",
                  "status": "active",
                  "created_at": "2026-09-06T08:00:00Z",
                  "updated_at": "2026-09-06T08:00:01Z"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - deposit creation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Not Implemented - deposit is not supported for this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": 501,
                    "message": "Deposit is not supported for this project",
                    "details": []
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```