Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Payout Recipients

Manage saved payout recipients for crypto and fiat in one place

List payout recipients

get
/api/v1/recipients

Returns your saved payout recipients. Filter by type to return a single rail, or omit type to return all types.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Query parameters
pagenumber · min: 1Optional

Page number (1-based)

Default: 1Example: 1
sizenumber · min: 1 · max: 100Optional

Number of items per page

Default: 10Example: 10
isTemporarybooleanOptional

Omit for all recipients; true for temporary, false for address book.

typestring · enumOptional

Filter by recipient type. Omit to list every type.

Possible values:
customerIdstringOptional

Filter by the customer the recipient is linked to.

Example: b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11
searchstringOptional

Search by account holder name, institution, or label.

Example: payroll
Responses
200

Recipients retrieved.

application/json
successbooleanRequired

Indicates if the request was successful

Example: true
messagestringRequired

Response message

Example: Success
get/api/v1/recipients
GET /api/v1/recipients HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*
200

Recipients retrieved.

{
  "success": true,
  "message": "Recipients retrieved successfully",
  "data": [
    {
      "id": "b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11",
      "type": "ngn_bank_account",
      "label": "Payroll GTBank",
      "isDefault": true,
      "isTrusted": false,
      "details": {
        "accountName": "JOHN ADEYEMI DOE",
        "accountNumber": "******6789",
        "bankName": "Guaranty Trust Bank",
        "bankCode": "058",
        "accountType": "savings",
        "currency": "NGN"
      },
      "createdAt": "2026-06-27T10:20:05.000Z",
      "updatedAt": "2026-06-27T10:20:05.000Z"
    },
    {
      "id": "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454",
      "type": "crypto_address",
      "label": "Treasury TRON wallet",
      "isDefault": true,
      "isTrusted": false,
      "details": {
        "chain": "tron",
        "address": "TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"
      },
      "createdAt": "2026-06-27T10:14:32.000Z",
      "updatedAt": "2026-06-27T10:14:32.000Z"
    },
    {
      "id": "3a7f2b90-5c1d-4e8a-b6f4-9d0c2e5a7b31",
      "type": "kes_mobile_money",
      "label": "Nairobi supplier",
      "isDefault": false,
      "isTrusted": false,
      "details": {
        "currency": "KES",
        "countryIsoCode": "KE",
        "accountNumber": "******5678",
        "accountName": "Jane Wanjiku",
        "institutionCode": "MPESA",
        "institutionName": "M-Pesa",
        "accountType": "individual"
      },
      "createdAt": "2026-06-27T10:26:48.000Z",
      "updatedAt": "2026-06-27T10:26:48.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "size": 10,
    "total": 3,
    "totalPages": 1
  }
}

Create payout recipient

post
/api/v1/recipients

Adds a payout recipient. Set type to crypto_address, ngn_bank_account, kes_mobile_money (Kenya) or ghs_mobile_money (Ghana) and supply the matching details. Bank accounts are verified and must match your name or business name. If a matching recipient already exists, the existing one is returned instead of creating a duplicate.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Body
isTemporarybooleanOptional

True for a one-time recipient that is not saved to the address book. Defaults to false.

notesstring · max: 500Optional

Merchant notes about this recipient. Use an empty string to clear.

typestring · enumRequired

Recipient type. Determines the shape of details.

Example: ngn_bank_accountPossible values:
labelstringOptional

Friendly label for the recipient.

Example: Payroll GTBank
detailsone ofRequired

Type-specific details. crypto_address: { chain, address }. ngn_bank_account: { accountNumber, bankCode, accountType? }. kes_mobile_money and ghs_mobile_money: { phoneNumber, accountName, institutionCode, accountType? }.

or
or
Responses
201

Recipient created, or the existing recipient if it already existed.

application/json
successbooleanRequiredExample: true
messagestringRequiredExample: Recipient created successfully
post/api/v1/recipients
POST /api/v1/recipients HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "isTemporary": true,
  "notes": "text",
  "type": "ngn_bank_account",
  "label": "Payroll GTBank",
  "details": {
    "chain": "tron",
    "address": "TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"
  }
}
{
  "success": true,
  "message": "Recipient created successfully",
  "data": {
    "id": "b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11",
    "type": "ngn_bank_account",
    "label": "Payroll GTBank",
    "isDefault": true,
    "isTrusted": false,
    "details": {
      "accountName": "JOHN ADEYEMI DOE",
      "accountNumber": "******6789",
      "bankName": "Guaranty Trust Bank",
      "bankCode": "058",
      "accountType": "savings",
      "currency": "NGN"
    },
    "createdAt": "2026-06-27T10:20:05.000Z",
    "updatedAt": "2026-06-27T10:20:05.000Z"
  }
}

Validate recipient details

post
/api/v1/recipients/validate

Preflight check before creating a recipient. Crypto validates the address format. Bank resolves the account holder name through the provider. Mobile money resolves the corridor and provider for the details.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Body
typestring · enumRequiredExample: ngn_bank_accountPossible values:
detailsone ofRequired

Type-specific details to validate. crypto_address: { chain, address }. ngn_bank_account: { accountNumber, bankCode }. kes_mobile_money and ghs_mobile_money take the same details as create.

or
or
Responses
200

Details are valid.

application/json
validbooleanRequiredExample: true
typestring · enumRequiredExample: ngn_bank_accountPossible values:
resolvedobjectRequired

Resolved details, matching type. crypto_address: { chain, address }. ngn_bank_account: { accountName, bankName, bankCode, accountNumber }. kes_mobile_money and ghs_mobile_money: { currency, countryIsoCode, accountNumber, accountName, institutionCode, institutionName, accountType }.

post/api/v1/recipients/validate
POST /api/v1/recipients/validate HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 101

{
  "type": "ngn_bank_account",
  "details": {
    "chain": "tron",
    "address": "TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"
  }
}
{
  "success": true,
  "message": "Recipient details are valid",
  "data": {
    "valid": true,
    "type": "ngn_bank_account",
    "resolved": {
      "accountName": "JOHN ADEYEMI DOE",
      "bankName": "Guaranty Trust Bank",
      "bankCode": "058",
      "accountNumber": "0123456789"
    }
  }
}

List supported banks

get
/api/v1/recipients/banks

Banks available for bank account recipients. Nigeria (ng) only for now.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Query parameters
countrystringOptional

ISO 3166-1 alpha-2 country code. Optional, defaults to ng; only ng is supported for now.

Default: ngExample: ng
Responses
200

Bank list retrieved.

application/json
successbooleanRequiredExample: true
messagestringRequiredExample: Bank list retrieved successfully
get/api/v1/recipients/banks
GET /api/v1/recipients/banks HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*
200

Bank list retrieved.

{
  "success": true,
  "message": "Bank list retrieved successfully",
  "data": {
    "status": true,
    "message": "success",
    "data": [
      {
        "name": "Access Bank Nigeria",
        "slug": "access",
        "code": "044",
        "nibss_bank_code": "000014",
        "country": "NG"
      }
    ]
  }
}

List supported payout chains

get
/api/v1/recipients/chains

Returns the chains and assets available for crypto_address recipients, keyed by chain.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Responses
200

Supported chains retrieved.

application/json
successbooleanRequiredExample: true
messagestringRequiredExample: Supported payout chains retrieved successfully
get/api/v1/recipients/chains
GET /api/v1/recipients/chains HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*
200

Supported chains retrieved.

{
  "success": true,
  "message": "Supported payout chains retrieved successfully",
  "data": {
    "tron": [
      {
        "asset": "USDT",
        "networkId": "tron:0000000000000000000000000000000000000000",
        "metadata": {
          "name": "Tether USD",
          "symbol": "USDT",
          "decimals": 6
        },
        "contract": {
          "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
          "decimals": 6
        }
      }
    ],
    "base": [
      {
        "asset": "USDC",
        "networkId": "eip155:8453",
        "metadata": {
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": 6
        },
        "contract": {
          "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "decimals": 6
        }
      }
    ],
    "bsc": [
      {
        "asset": "USDT",
        "networkId": "eip155:56",
        "metadata": {
          "name": "Tether USD",
          "symbol": "USDT",
          "decimals": 6
        },
        "contract": {
          "address": "0x55d398326f99059ff775485246999027b3197955",
          "decimals": 18
        }
      }
    ]
  }
}

Retrieve payout recipient

get
/api/v1/recipients/{id}

Returns the payout recipient for the given ID.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters
idstringRequired

Recipient ID

Responses
200

Recipient retrieved.

application/json
successbooleanRequiredExample: true
messagestringRequiredExample: Recipient created successfully
get/api/v1/recipients/{id}
GET /api/v1/recipients/{id} HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "Recipient retrieved successfully",
  "data": {
    "id": "b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11",
    "type": "ngn_bank_account",
    "label": "Payroll GTBank",
    "isDefault": true,
    "isTrusted": false,
    "details": {
      "accountName": "JOHN ADEYEMI DOE",
      "accountNumber": "******6789",
      "bankName": "Guaranty Trust Bank",
      "bankCode": "058",
      "accountType": "savings",
      "currency": "NGN"
    },
    "createdAt": "2026-06-27T10:20:05.000Z",
    "updatedAt": "2026-06-27T10:20:05.000Z"
  }
}

Delete payout recipient

delete
/api/v1/recipients/{id}

Deletes the payout recipient.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters
idstringRequired

Recipient ID

Responses
200

Recipient deleted.

application/json
delete/api/v1/recipients/{id}
DELETE /api/v1/recipients/{id} HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "Recipient deleted successfully",
  "data": {
    "success": true
  }
}
PreviousPayouts
NextBalance

Last updated

Was this helpful?