Token Mutations

The Token API provides several mutations for managing saved addresses and processing withdrawals.

Saved Address Management

createSavedAddress

Create a new saved withdrawal address.

createSavedAddress(input: CreateSavedAddressInput!): UserSavedAddressModel!

Arguments:

Name	Type	Description	Required
input	CreateSavedAddressInput	The saved address data	Yes

Input Fields:

Name	Type	Description	Required	Validation
label	String	User-defined label for the address	Yes	Max length: 64
tokenId	String	Token ID	Yes	Non-empty
chain	String	Chain name	Yes	Non-empty
address	String	Wallet address	Yes	Max length: 256
tag	String	Tag or memo (for certain chains)	No	Max length: 256

Returns: UserSavedAddressModel

Authentication: Required (USER role)

Example:

mutation {
  createSavedAddress(
    input: {
      label: "My BTC Wallet"
      tokenId: "bitcoin"
      chain: BITCOIN
      address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
    }
  ) {
    id
    name
    chain
    address
  }
}

cancelPendingWithdrawal

Cancel a pending withdrawal request.

cancelPendingWithdrawal(id: String!): Boolean!

Arguments:

Field	Type	Description
id	String!	The withdrawal ID to cancel

Returns: Boolean - true if the withdrawal was successfully canceled, false otherwise

Authentication: Required (USER role)

Example:

mutation {
  cancelPendingWithdrawal(id: "680b6b0350b2cf76217aab0b")
}

Error Handling:

• Returns false if the withdrawal request is not found
• Returns false if the withdrawal is not in a cancellable state
• Throws an error if the withdrawal belongs to a different user
• Throws an error if there are any issues with the cancellation process

Notes:

• Only withdrawals with status REQUESTED can be canceled
• The cancellation process is atomic and uses a lock mechanism to prevent race conditions
• After cancellation, the withdrawal status is updated to CANCELLED
• The system will attempt to process the cancellation through the BadHombre API

updateSavedAddress

Update an existing saved withdrawal address.

updateSavedAddress(id: String!, input: UpdateSavedAddressInput!): UserSavedAddressModel!

Arguments:

Name	Type	Description	Required
id	String	Saved address ID	Yes
input	UpdateSavedAddressInput	The updated saved address data	Yes

Input Fields:

Name	Type	Description	Required	Validation
label	String	User-defined label for the address	Yes	Max length: 64
address	String	Wallet address	Yes	Max length: 256
tag	String	Tag or memo (for certain chains)	No	Max length: 256

Returns: UserSavedAddressModel

Authentication: Required (USER role)

Example:

mutation {
  updateSavedAddress(
    id: "12345"
    input: {
      label: "My Updated BTC Wallet"
      address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
    }
  ) {
    id
    label
    tokenId
    chain
    address
  }
}

deleteSavedAddress

Delete a saved withdrawal address.

deleteSavedAddress(id: String!): Boolean!

Arguments:

Name	Type	Description	Required
id	String	Saved address ID	Yes

Returns: Boolean indicating success

Authentication: Required (USER role)

Example:

mutation {
  deleteSavedAddress(id: "12345")
}

Withdrawal Operations

withdraw

Submit a withdrawal request.

withdraw(input: WithdrawInput!): Boolean!

Arguments:

Name	Type	Description	Required
input	WithdrawInput	The withdrawal request data	Yes

Input Fields:

Name	Type	Description	Required	Validation
tokenId	String	Token ID	Yes	Non-empty
chain	String	Chain name	Yes	Non-empty
address	String	Destination wallet address	Yes	Max length: 256
tag	String	Tag or memo (for certain chains)	No	Max length: 256
amount	Float	Amount to withdraw	Yes	Min: 0

Returns: Boolean indicating success

Authentication: Required (USER role)

Example:

mutation {
  withdraw(
    input: {
      tokenId: "bitcoin"
      chain: "BTC"
      address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
      amount: 0.1
    }
  )
}

Error Handling

The Token API mutations handle errors by throwing appropriate exceptions, which are converted to GraphQL errors with status codes and messages. Common errors include:

Saved Address Errors

• Not Found Error: When a saved address with the specified ID does not exist
• Unauthorized Error: When a user tries to update or delete another user's saved address
• Validation Error: When the input data does not meet validation requirements
• Duplicate Error: When a user tries to create a saved address with a label that already exists

Withdrawal Errors

• Insufficient Balance Error: When a user tries to withdraw more than their available balance
• Minimum Amount Error: When a withdrawal amount is below the minimum allowed for the token and chain
• Validation Error: When the input data does not meet validation requirements
• User Verification Error: When a user who is not verified tries to make a withdrawal
• Service Error: When the external service (BadhombreAPI) fails to process the withdrawal

Security Considerations

All Token API mutations require authentication through JWT tokens and authorization through role-based access control. The mutations require the USER role, ensuring that only authenticated users can perform these operations.

In addition, withdrawal operations may have additional security measures:

1. User Verification: Users must be verified (KYC/AML) to perform withdrawals
2. Withdrawal Limits: Users may have daily/monthly withdrawal limits
3. Address Validation: Destination addresses are validated for the correct format
4. Two-Factor Authentication: Some withdrawals may require 2FA confirmation
5. Email Confirmation: Some withdrawals may require email confirmation