Create a wallet credential

curl --request POST \
  --url https://api.globalstack.io/v1/wallets/{id}/credentials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "network": "bank",
  "currency": "NGN",
  "country_code": "NG",
  "label": "<string>",
  "metadata": {},
  "merchantReference": "<string>"
}
'

import requests

url = "https://api.globalstack.io/v1/wallets/{id}/credentials"

payload = {
    "network": "bank",
    "currency": "NGN",
    "country_code": "NG",
    "label": "<string>",
    "metadata": {},
    "merchantReference": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    network: 'bank',
    currency: 'NGN',
    country_code: 'NG',
    label: '<string>',
    metadata: {},
    merchantReference: '<string>'
  })
};

fetch('https://api.globalstack.io/v1/wallets/{id}/credentials', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.globalstack.io/v1/wallets/{id}/credentials",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'network' => 'bank',
    'currency' => 'NGN',
    'country_code' => 'NG',
    'label' => '<string>',
    'metadata' => [
        
    ],
    'merchantReference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.globalstack.io/v1/wallets/{id}/credentials"

	payload := strings.NewReader("{\n  \"network\": \"bank\",\n  \"currency\": \"NGN\",\n  \"country_code\": \"NG\",\n  \"label\": \"<string>\",\n  \"metadata\": {},\n  \"merchantReference\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.globalstack.io/v1/wallets/{id}/credentials")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"network\": \"bank\",\n  \"currency\": \"NGN\",\n  \"country_code\": \"NG\",\n  \"label\": \"<string>\",\n  \"metadata\": {},\n  \"merchantReference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.globalstack.io/v1/wallets/{id}/credentials")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"network\": \"bank\",\n  \"currency\": \"NGN\",\n  \"country_code\": \"NG\",\n  \"label\": \"<string>\",\n  \"metadata\": {},\n  \"merchantReference\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": true,
  "message": "Wallet credential created successfully",
  "code": "ok",
  "data": {
    "id": "wcr_01HXYZABC1234567890ABCDEFG",
    "type": "crypto",
    "currency": "USDC",
    "network": "base",
    "wallet": {
      "id": "wal_01HXYZABC1234567890ABCDEFG",
      "currency": "USDC",
      "label": "USDC Wallet"
    },
    "metadata": {
      "team": "ops"
    },
    "details": {
      "accountName": "Medard Ilunga",
      "accountNumber": "1234567890",
      "bankName": "Wema Bank",
      "bankCode": "035",
      "currency": "NGN",
      "reference": "GSVRYTZ496CM"
    },
    "status": "pending",
    "created_at": "2026-05-20T12:00:00.000Z",
    "updated_at": "2026-05-20T12:00:00.000Z",
    "label": "Treasury deposit"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

{
  "status": false,
  "message": "Resource not found",
  "code": "not_found",
  "data": null,
  "meta": {
    "next_steps": {
      "action": "Verify the resource identifier and retry.",
      "docs_url": "https://docs.globalstack.io/errors#not_found"
    },
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

{
  "status": false,
  "message": "Resource not found",
  "code": "not_found",
  "data": null,
  "meta": {
    "next_steps": {
      "action": "Verify the resource identifier and retry.",
      "docs_url": "https://docs.globalstack.io/errors#not_found"
    },
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

{
  "status": false,
  "message": "Resource not found",
  "code": "not_found",
  "data": null,
  "meta": {
    "next_steps": {
      "action": "Verify the resource identifier and retry.",
      "docs_url": "https://docs.globalstack.io/errors#not_found"
    },
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

{
  "status": false,
  "message": "Resource not found",
  "code": "not_found",
  "data": null,
  "meta": {
    "next_steps": {
      "action": "Verify the resource identifier and retry.",
      "docs_url": "https://docs.globalstack.io/errors#not_found"
    },
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Wallets

Create a wallet credential

Create a fiat or crypto funding credential on a wallet identified by the wal_… id in the path.

Same-currency credentials (default)

By default the credential’s currency matches the wallet’s currency — deposits land directly on the wallet balance. network must be a network supported by the wallet’s currency (e.g. base, ethereum, solana for crypto). For fiat credentials only bank is supported today — even if the wallet’s currency advertises other fiat networks (e.g. mobile_money), a non-bank network is rejected with invalid_input. type is optional — when omitted it is derived from the wallet’s currency; when supplied it must match the wallet’s currency type. merchantReference is optional and is generated when not provided.

Cross-currency credentials (auto-onramp / auto-offramp)

Passing an explicit currency different from the wallet’s currency creates a cross-currency credential. Every deposit is automatically converted into the wallet’s currency at the FX rate live at deposit time:

Auto-onramp — a fiat currency on a crypto wallet (e.g. NGN on a USDC wallet). The payer sends fiat; the wallet is credited in crypto.
Auto-offramp — a crypto currency on a fiat wallet (e.g. USDC on an NGN wallet). The payer sends crypto; the wallet is credited in fiat.

Only crypto↔fiat pairs are supported — a crypto credential on a crypto wallet (or fiat on fiat) is rejected. Both currencies in the pair must have matching capabilities: canOnramp for auto-onramp, canOfframp for auto-offramp. network is validated against the credential’s own currency, not the wallet’s — so an NGN credential on a USDC wallet uses bank, and a USDC credential on an NGN wallet uses base / ethereum / solana.

Disambiguating multi-country currencies (`country_code`)

Some fiat currency codes exist for more than one country (e.g. XOF for CFA-franc countries). Pass an ISO 3166-1 alpha-2 country_code to pin which country’s currency the credential should hold:

Cross-currency — when currency resolves to multiple country rows and no country_code is supplied, the request is rejected with invalid_input and the response message lists the available countries. When country_code is supplied, the credential currency is pinned to that country (falling back to the null-country row for crypto codes).
Same-currency — the credential inherits the wallet’s currency and its country, so no lookup happens. If country_code is supplied it must equal the parent wallet’s country or the request is rejected with invalid_input.

POST

wallets

{id}

credentials

Create a wallet credential

curl --request POST \
  --url https://api.globalstack.io/v1/wallets/{id}/credentials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "network": "bank",
  "currency": "NGN",
  "country_code": "NG",
  "label": "<string>",
  "metadata": {},
  "merchantReference": "<string>"
}
'

import requests

url = "https://api.globalstack.io/v1/wallets/{id}/credentials"

payload = {
    "network": "bank",
    "currency": "NGN",
    "country_code": "NG",
    "label": "<string>",
    "metadata": {},
    "merchantReference": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    network: 'bank',
    currency: 'NGN',
    country_code: 'NG',
    label: '<string>',
    metadata: {},
    merchantReference: '<string>'
  })
};

fetch('https://api.globalstack.io/v1/wallets/{id}/credentials', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.globalstack.io/v1/wallets/{id}/credentials",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'network' => 'bank',
    'currency' => 'NGN',
    'country_code' => 'NG',
    'label' => '<string>',
    'metadata' => [
        
    ],
    'merchantReference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.globalstack.io/v1/wallets/{id}/credentials"

	payload := strings.NewReader("{\n  \"network\": \"bank\",\n  \"currency\": \"NGN\",\n  \"country_code\": \"NG\",\n  \"label\": \"<string>\",\n  \"metadata\": {},\n  \"merchantReference\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.globalstack.io/v1/wallets/{id}/credentials")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"network\": \"bank\",\n  \"currency\": \"NGN\",\n  \"country_code\": \"NG\",\n  \"label\": \"<string>\",\n  \"metadata\": {},\n  \"merchantReference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.globalstack.io/v1/wallets/{id}/credentials")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"network\": \"bank\",\n  \"currency\": \"NGN\",\n  \"country_code\": \"NG\",\n  \"label\": \"<string>\",\n  \"metadata\": {},\n  \"merchantReference\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": true,
  "message": "Wallet credential created successfully",
  "code": "ok",
  "data": {
    "id": "wcr_01HXYZABC1234567890ABCDEFG",
    "type": "crypto",
    "currency": "USDC",
    "network": "base",
    "wallet": {
      "id": "wal_01HXYZABC1234567890ABCDEFG",
      "currency": "USDC",
      "label": "USDC Wallet"
    },
    "metadata": {
      "team": "ops"
    },
    "details": {
      "accountName": "Medard Ilunga",
      "accountNumber": "1234567890",
      "bankName": "Wema Bank",
      "bankCode": "035",
      "currency": "NGN",
      "reference": "GSVRYTZ496CM"
    },
    "status": "pending",
    "created_at": "2026-05-20T12:00:00.000Z",
    "updated_at": "2026-05-20T12:00:00.000Z",
    "label": "Treasury deposit"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

{
  "status": false,
  "message": "Resource not found",
  "code": "not_found",
  "data": null,
  "meta": {
    "next_steps": {
      "action": "Verify the resource identifier and retry.",
      "docs_url": "https://docs.globalstack.io/errors#not_found"
    },
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

{
  "status": false,
  "message": "Resource not found",
  "code": "not_found",
  "data": null,
  "meta": {
    "next_steps": {
      "action": "Verify the resource identifier and retry.",
      "docs_url": "https://docs.globalstack.io/errors#not_found"
    },
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

{
  "status": false,
  "message": "Resource not found",
  "code": "not_found",
  "data": null,
  "meta": {
    "next_steps": {
      "action": "Verify the resource identifier and retry.",
      "docs_url": "https://docs.globalstack.io/errors#not_found"
    },
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

{
  "status": false,
  "message": "Resource not found",
  "code": "not_found",
  "data": null,
  "meta": {
    "next_steps": {
      "action": "Verify the resource identifier and retry.",
      "docs_url": "https://docs.globalstack.io/errors#not_found"
    },
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Headers

Idempotency-Key

string

Optional client-supplied key. Identical key + identical body within 24h replays the original response. Identical key + different body returns 409 idempotency_conflict. The hash is over raw bytes — clients retrying must send the byte-identical body; a re-serialised JSON payload will produce a different hash and a 409. Strongly recommended for retry-safe clients.

Pattern: ^[A-Za-z0-9_\-]{8,255}$

Body

application/json

CreateCredentialDto

network

enum<string>

required

Available options:

mobile_money,

bank,

solana,

base,

ethereum

Example:

"bank"

type

enum<string>

Available options:

crypto,

fiat

currency

string

Pattern: ^[A-Z]{2,10}$

Example:

"NGN"

country_code

string

Pattern: ^[A-Z]{2}$

Example:

"NG"

label

string

Maximum string length: 128

metadata

object

merchantReference

string

Maximum string length: 128

Response

Wallet credential created successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Wallet credential created successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes

Wallets

Transfers

Transactions

Quotes

Onramps

Offramps

Notification Webhooks

Customers

Me

Supported Currencies

Supported Countries

Conversions

Beneficiaries

Create a wallet credential

Same-currency credentials (default)

Cross-currency credentials (auto-onramp / auto-offramp)

Disambiguating multi-country currencies (`country_code`)

Authorizations

Headers

Body

Response