Wallet Provisioning

Create and manage wallets for your users via the Partner API. Each wallet gets an EVM address (and optionally a Solana address) with access to Bankr APIs based on your organization's capabilities.

All endpoints in this section authenticate with the X-Partner-Key header. See API Keys for setup.

Create a Wallet

POST /partner/wallets

curl -X POST https://api.bankr.bot/partner/wallets \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY" \
  -d '{
    "idempotencyKey": "user-abc-123",
    "wallet": {
      "solana": true
    },
    "apiKey": {
      "permissions": {
        "agentApiEnabled": true,
        "llmGatewayEnabled": false,
        "tokenLaunchApiEnabled": false,
        "readOnly": false
      },
      "allowedIps": ["203.0.113.10"],
      "allowedRecipients": {
        "evm": ["0x5f8DA8F88eC81e27f2E22fCB9CA5D926c595E508"]
      }
    }
  }'

Request Body

Field	Type	Required	Description
`idempotencyKey`	string	No	Max 128 chars. Same key returns the same wallet on retry
`wallet.solana`	boolean	No	Create a Solana address alongside EVM. Requires `enableSolana` on your org
`apiKey`	object	No	Auto-generate a wallet API key at creation. See below

`apiKey` Fields

Field	Type	Description
`apiKey.permissions.agentApiEnabled`	boolean	Enable Agent API access. Requires org `agentApi` capability
`apiKey.permissions.llmGatewayEnabled`	boolean	Enable LLM Gateway access. Requires org `llmGatewayApi` capability
`apiKey.permissions.tokenLaunchApiEnabled`	boolean	Enable Token Launch access. Requires org `tokenLaunchApi` capability
`apiKey.permissions.readOnly`	boolean	Restrict to read-only operations (balances, prices — no transactions)
`apiKey.allowedIps`	string[]	Restrict this wallet's API key to specific IPs or CIDR ranges (e.g., `10.0.0.0/24`)
`apiKey.allowedRecipients.evm`	string[]	Allowlist of EVM addresses this wallet can send to
`apiKey.allowedRecipients.solana`	string[]	Allowlist of Solana addresses this wallet can send to

Response `201`

{
  "id": "wlt_A1b2C3d4E5f6G7h8",
  "evmAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "solAddress": "ABC123...xyz",
  "apiKey": "bk_usr_aBcD1234_secretKeyValue1234567890abcdef"
}

Field	Type	Description
`id`	string	Public wallet ID (`wlt_` prefix) — use this to look up or manage the wallet
`evmAddress`	string	EVM address on Base/Ethereum/Polygon
`solAddress`	string	Solana address. Only present if `wallet.solana: true`
`apiKey`	string	Wallet-level API key (`bk_usr_` prefix). Only present if `apiKey` was requested. This key can be used as `X-API-Key` for Agent API, Wallet API, and LLM Gateway calls

Idempotency

Always pass an idempotencyKey tied to your internal user ID. If the request is retried, the same wallet is returned (status 200) instead of creating a duplicate. The key is scoped to your organization.

Errors

Status	Error	Cause
`400`	Validation error	Invalid body — check `details` array for specifics
`403`	`Wallet provisioning is not enabled for this organization`	Org has no `walletProvisioning` config
`403`	`Wallet API capability is not enabled for this organization`	`walletApi` not enabled
`403`	`Solana wallet provisioning is not enabled for this organization`	`wallet.solana: true` but `enableSolana` is false
`403`	`<capability> API capability is not enabled for this organization`	Requested permission exceeds org capabilities
`403`	`Wallet provisioning quota exceeded`	Hit `maxWallets` limit

List Wallets

GET /partner/wallets

curl "https://api.bankr.bot/partner/wallets?limit=20&skip=0" \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY"

Query Parameters

Param	Type	Default	Max	Description
`limit`	number	20	100	Wallets per page
`skip`	number	0	—	Offset for pagination

Response `200`

{
  "wallets": [
    {
      "id": "wlt_A1b2C3d4E5f6G7h8",
      "evmAddress": "0x1234...5678",
      "solAddress": "ABC...xyz",
      "status": "active",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 42
}

Get Wallet Details

GET /partner/wallets/:identifier

Look up a wallet by its public ID, EVM address, or Solana address:

# By public ID
curl https://api.bankr.bot/partner/wallets/wlt_A1b2C3d4E5f6G7h8 \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY"

# By EVM address
curl https://api.bankr.bot/partner/wallets/0x1234567890abcdef1234567890abcdef12345678 \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY"

# By Solana address
curl https://api.bankr.bot/partner/wallets/ABC123xyz \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY"

Identifier Resolution

Format	Lookup
Starts with `wlt_`	Public wallet ID
Starts with `0x`	EVM address
Otherwise	Solana address

The wallet must belong to your organization. Wallets provisioned by other partners return 404.

Response `200`

{
  "id": "wlt_A1b2C3d4E5f6G7h8",
  "evmAddress": "0x1234...5678",
  "solAddress": "ABC...xyz",
  "status": "active",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "apiKey": {
    "isActive": true,
    "walletApiEnabled": true,
    "agentApiEnabled": true,
    "llmGatewayEnabled": false,
    "tokenLaunchApiEnabled": false,
    "readOnly": false,
    "allowedIps": ["203.0.113.10"],
    "allowedRecipients": {
      "evm": ["0x5f8D...E508"],
      "solana": []
    },
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

The apiKey field is present only if the wallet has an active API key. It never contains the secret — only metadata and permissions.

Generate or Rotate a Wallet API Key

POST /partner/wallets/:identifier/api-key

Creates a new API key for the wallet. If one already exists, all previous keys are revoked and replaced.

curl -X POST https://api.bankr.bot/partner/wallets/wlt_A1b2C3d4E5f6G7h8/api-key \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY" \
  -d '{
    "permissions": {
      "agentApiEnabled": true
    },
    "allowedIps": [],
    "allowedRecipients": {
      "evm": ["0x5f8DA8F88eC81e27f2E22fCB9CA5D926c595E508"]
    }
  }'

Request Body

Same schema as the apiKey field in Create a Wallet. All fields are optional.

Response `201`

{
  "apiKey": "bk_usr_aBcD1234_secretKeyValue1234567890abcdef"
}

warning

This replaces any existing key. The previous key stops working immediately. The new secret is only shown once.

Errors

Status	Error	Cause
`403`	`Wallet is permanently closed`	Cannot create keys for a closed wallet
`403`	`Wallet is suspended`	Cannot create keys for a suspended wallet
`403`	`<capability> API capability is not enabled`	Requested permission exceeds org capabilities
`404`	`Wallet not found`	Identifier not found or wallet belongs to another partner

Revoke a Wallet API Key

DELETE /partner/wallets/:identifier/api-key

Deactivates all API keys for this wallet. The wallet continues to exist but can no longer authenticate to Bankr APIs directly.

curl -X DELETE https://api.bankr.bot/partner/wallets/wlt_A1b2C3d4E5f6G7h8/api-key \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY"

Response `200`

{
  "success": true
}

Fund a Wallet

POST /partner/wallets/:identifier/fund

Transfer native ETH and/or ERC20 tokens from the org wallet to a provisioned wallet. Supports up to 3 tokens per request. ERC20 tokens are batched into a single on-chain transaction via the Transfer Helper contract.

info

Requires an org wallet to be configured for your partner organization. The org wallet must have sufficient balance for all requested tokens.

Request Body

Field	Type	Required	Description
`tokens`	array	Yes	1–3 token transfers
`tokens[].tokenAddress`	string	Yes	`"native"` for ETH, or `0x`-prefixed ERC20 address
`tokens[].amount`	string	Yes	Human-readable decimal amount (e.g. `"0.01"`, `"100"`)
`chain`	string	No	`"base"` (default), `"polygon"`, `"mainnet"`, or `"unichain"`

curl -X POST https://api.bankr.bot/partner/wallets/0xABC.../fund \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": [
      { "tokenAddress": "native", "amount": "0.001" },
      { "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "10" }
    ],
    "chain": "base"
  }'

Response `200`

{
  "success": true,
  "results": [
    { "tokenAddress": "native", "amount": "0.001", "success": true, "txHash": "0x..." },
    { "tokenAddress": "0x833...", "amount": "10", "success": true, "txHash": "0x..." }
  ]
}

Errors

Status	Error	Cause
`400`	Insufficient org wallet balance	One or more tokens have insufficient balance (details in response)
`400`	Invalid request body	Invalid token address, amount, >3 tokens, or duplicates
`403`	Wallet is suspended / closed	Target wallet is not active
`404`	No org wallet configured	Org does not have an org wallet set up
`404`	Wallet not found	Target wallet does not exist or is not owned by this organization

Funding during provisioning

You can also fund a wallet at creation time by adding a fund field to the POST /partner/wallets request:

curl -X POST https://api.bankr.bot/partner/wallets \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fund": {
      "tokens": [{ "tokenAddress": "native", "amount": "0.001" }],
      "chain": "base"
    }
  }'

The wallet is always created regardless of funding outcome. The response includes a fund field with per-token results.

Suspend a Wallet

POST /partner/wallets/:identifier/suspend

Temporarily suspends a wallet. All API keys are deactivated — the wallet can no longer authenticate to Bankr APIs. The wallet's on-chain funds are unaffected.

curl -X POST https://api.bankr.bot/partner/wallets/wlt_A1b2C3d4E5f6G7h8/suspend \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY"

Response `200`

{
  "status": "suspended"
}

Idempotent — calling suspend on an already-suspended wallet returns 200.

Errors

Status	Error	Cause
`403`	`Wallet is permanently closed`	Cannot suspend a closed wallet
`404`	`Wallet not found`	Identifier not found or wallet belongs to another partner

Resume a Wallet

POST /partner/wallets/:identifier/resume

Resumes a suspended wallet. The wallet status returns to active, but API keys are NOT reactivated — you must create a new key after resuming.

curl -X POST https://api.bankr.bot/partner/wallets/wlt_A1b2C3d4E5f6G7h8/resume \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY"

Response `200`

{
  "status": "active"
}

Idempotent — calling resume on an already-active wallet returns 200.

warning

Resume does not reactivate previously revoked API keys. This is intentional — if a key was compromised before the suspend, it should not be automatically restored. Always create a new key after resuming.

Errors

Status	Error	Cause
`403`	`Wallet is permanently closed`	Cannot resume a closed wallet
`404`	`Wallet not found`	Identifier not found or wallet belongs to another partner

Close a Wallet

POST /partner/wallets/:identifier/close

Permanently closes a wallet. All API keys are deactivated. This action cannot be undone — there is no reopen path.

curl -X POST https://api.bankr.bot/partner/wallets/wlt_A1b2C3d4E5f6G7h8/close \
  -H "X-Partner-Key: bk_ptr_YOUR_KEY"

Response `200`

{
  "status": "closed",
  "closedAt": "2026-04-09T12:00:00.000Z"
}

Idempotent — calling close on an already-closed wallet returns 200.

danger

Closing a wallet is permanent. Drain any remaining funds before closing. There is no fund recovery mechanism for closed wallets.

Errors

Status	Error	Cause
`404`	`Wallet not found`	Identifier not found or wallet belongs to another partner

Wallet Status

Wallets have a status field returned in List Wallets and Get Wallet Details:

Status	Description	Can create API keys?	Can use APIs?
`active`	Normal operation	Yes	Yes
`suspended`	Temporarily frozen	No	No
`closed`	Permanently shut down	No	No

Quotas

Your organization has a maximum number of wallets it can provision (maxWallets). The current count (walletsCreated) is incremented atomically on each creation. When the limit is reached, creation requests return 403.

Check your quota from the partner dashboard:

{
  "walletProvisioning": {
    "maxWallets": 1000,
    "walletsCreated": 42,
    "enableSolana": true,
    "allowedCapabilities": {
      "walletApi": true,
      "agentApi": true,
      "llmGatewayApi": true,
      "tokenLaunchApi": false
    }
  }
}

Contact the Bankr team to increase your quota.

What Provisioned Wallets Can Do

Once a wallet is provisioned with an API key, it authenticates to Bankr APIs using the X-API-Key header — the same way any Bankr user would. The difference is that access is scoped by your org's capabilities and the key's permissions.

API	Header	Docs	Requires
Wallet API	`X-API-Key`	Wallet API	`walletApi` capability (always on)
Agent API	`X-API-Key`	Authentication	`agentApi` capability + `agentApiEnabled` permission
Token Launching	`X-API-Key`	Token Launching	`tokenLaunchApi` capability + `tokenLaunchApiEnabled` permission
LLM Gateway	`Authorization: Bearer <apiKey>`	LLM Gateway API	`llmGatewayApi` capability + `llmGatewayEnabled` permission

Create a Wallet​

Request Body​

apiKey Fields​

Response 201​

Errors​

List Wallets​

Query Parameters​

Response 200​

Get Wallet Details​

Identifier Resolution​

Response 200​

Generate or Rotate a Wallet API Key​

Request Body​

Response 201​

Errors​

Revoke a Wallet API Key​

Response 200​

Fund a Wallet​

Request Body​

Response 200​

Errors​

Funding during provisioning​

Suspend a Wallet​

Response 200​

Errors​

Resume a Wallet​

Response 200​

Errors​

Close a Wallet​

Response 200​

Errors​

Wallet Status​

Quotas​

What Provisioned Wallets Can Do​

Create a Wallet

Request Body

`apiKey` Fields

Response `201`

Errors

List Wallets

Query Parameters

Response `200`

Get Wallet Details

Identifier Resolution

Response `200`

Generate or Rotate a Wallet API Key

Request Body

Response `201`

Errors

Revoke a Wallet API Key

Response `200`

Fund a Wallet

Request Body

Response `200`

Errors

Funding during provisioning

Suspend a Wallet

Response `200`

Errors

Resume a Wallet

Response `200`

Errors

Close a Wallet

Response `200`

Errors

Wallet Status

Quotas

What Provisioned Wallets Can Do