Wallet addresses

Last reviewed: Sep 21, 2026

Each of your customers’ payment accounts must be associated with at least one wallet address for the account to be able to send and receive payments over Interledger and Open Payments. A wallet address serves as a publicly shareable standardized ID for a payment account.

Wallet addresses are created and hosted in Rafiki. However, the mapping of a wallet address to a customer account stays with you and is never stored in Rafiki’s database tables.

Wallet address requirements

Your Rafiki instance must be set up with at least one asset before wallet addresses can be created as each wallet address must have an asset assigned to it.
Wallet address structure is determined by the financial service provider (FSP). Consider whether your chosen naming conventions could disclose personal data. For example, choosing to issue addresses using first and last names.
Wallet address URLs are treated as case-insensitive, meaning that both lowercase and uppercase variations of the same address will be recognized as identical.
Operators must configure a wallet address base for each tenant. When creating wallet addresses, tenants are restricted to using this base.
Once the wallet address base (WALLET_ADDRESS_URL) is set for a tenant, it can’t be changed.

Create wallet addresses

There are a few ways you can create wallet addresses.

Through a script
In response to the wallet_address.not_found webhook event
In the Rafiki Admin app

Create wallet addresses through a script

Writing your own script that loops through your list of accounts is one way to batch-create wallet addresses for your existing account holders.

Ensure your script calls the createWalletAddress GraphQL mutation.

mutation CreateWalletAddress($input: CreateWalletAddressInput!) {
  createWalletAddress(input: $input) {
    code
    success
    message
    walletAddress {
      id
      createdAt
      publicName
      url
      asset {
        code
        id
        scale
      }
      tenantId
    }
  }
}

We strongly recommend you store at least the walletAddress.id in your internal database to be able to reference the account and wallet address later.

{
  "input": {
    "assetId": "0ddc0b7d-1822-4213-948e-915dda58850b",
    "publicName": "Sarah Marshall",
    "url": "https://example.wallet.com/sarah",
    "additionalProperties": [
      {
        "key": "iban",
        "value": "NL93 8601 1117 947",
        "visibleInOpenPayments": false
      },
      {
        "key": "nickname",
        "value": "S Mar",
        "visibleInOpenPayments": true
      }
    ]
  }
}

For more information about this mutation’s input object, see CreateWalletAddressInput.

{
  "data": {
    "createWalletAddress": {
      "code": "200",
      "success": true,
      "message": "Created wallet address",
      "walletAddress": {
        "id": "695e7546-1803-4b45-96b6-6a53f4082018",
        "createdAt": "2023-03-03T09:07:01.107Z",
        "publicName": "Sarah Marshall",
        "url": "https://example.wallet.com/sarah",
        "asset": {
          "id": "0ddc0b7d-1822-4213-948e-915dda58850b",
          "code": "USD",
          "scale": 2
        },
        "tenantId": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
  }
}

Create wallet addresses in response to a webhook event

The wallet_address.not_found event fires when a wallet address is requested through the Open Payments Get Wallet Address API, but Rafiki can’t find the address.

When you receive the event, look up the associated account in your system, then call the createWalletAddress mutation to create a wallet address for the account.

The mutation and example JSON request/response is the same as what’s given above.