Accounts

​

Before you create an account

• Consent. Create an account only after the user has agreed in your app, for example by tapping a button. That action is their consent to the API acting on the trade and withdrawal instructions you send for them. Send when they agreed and which terms they saw.
• Country. Send the user’s real country. Kash’s country rules, including the block on sanctioned countries, apply to it at trade and withdrawal time. Account creation itself does not refuse by country. Update it with PATCH if it changes.
• Destination. Register the user’s own address in your app. Every withdrawal goes there and nowhere else.

​

Create an account

curl -X POST "$KASH_API/partner/accounts" \
  -H "X-API-Key: $KASH_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-hsp-user-8841" \
  -d '{
    "externalId": "hsp-user-8841",
    "destination": { "network": "arc", "address": "0x2c7536e3605d9c16a7a3d7b1898e529396a65c23" },
    "country": "GB",
    "consent": { "acceptedAt": "2026-11-06T10:15:00Z", "termsVersion": "hsp-kash-terms-2026-11" },
    "email": "[email protected]"
  }'

{
  "account": {
    "accountId": "7a1c2e3d-4b5f-4a6e-8d7c-1b2a3c4d5e6f",
    "externalId": "hsp-user-8841",
    "status": "provisioning",
    "depositAddress": null,
    "destination": { "network": "arc", "address": "0x2c7536e3605d9c16a7a3d7b1898e529396a65c23" },
    "country": "GB",
    "createdAt": "2026-11-06T10:15:02.000Z"
  },
  "data": { "...": "the same account" },
  "_meta": { "requestId": "01HQGY8K2N3X4Z5C6D7E8F9G0H", "timestamp": "2026-11-06T10:15:02.120Z", "idempotent": false }
}

​

Creating the same account twice

• Same Idempotency-Key (a retry of the same request): the stored 202 is returned unchanged, with the header Idempotent-Replay: true. Nothing runs again.
• Different Idempotency-Key, same externalId: the existing account is returned with 200 and _meta.idempotent: true. The body you sent is not applied to it: to change its destination or country, use PATCH.
• After a release the externalId is free again. Creating it makes a new account with a new accountId.

​

Account statuses

​

When provisioning fails

​

Read and find accounts

# One account
curl "$KASH_API/partner/accounts/$ACCOUNT_ID" -H "X-API-Key: $KASH_PARTNER_KEY"

# The account you created for one of your users
curl "$KASH_API/partner/accounts?externalId=hsp-user-8841" -H "X-API-Key: $KASH_PARTNER_KEY"

# All accounts, newest first
curl "$KASH_API/partner/accounts?limit=50" -H "X-API-Key: $KASH_PARTNER_KEY"

​

Change the destination or country

curl -X PATCH "$KASH_API/partner/accounts/$ACCOUNT_ID" \
  -H "X-API-Key: $KASH_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "destination": { "network": "solana", "address": "8yYpcE7Jx9NmXNMGR6NGumBUu4UBpMTVQW44P9hwikyh" } }'

• Sending the destination the account already has changes nothing, does not restart the hold and sends no webhook.
• A country change takes effect for the next trade and withdrawal. It sends no webhook.
• A destination change answers 503 ROUTE_DISABLED when account changes are switched off, and 503 DEPENDENCY_UNAVAILABLE when that switch cannot be read. Nothing changed; retry.

​

Suspend and reactivate

curl -X POST "$KASH_API/partner/accounts/$ACCOUNT_ID/suspend" \
  -H "X-API-Key: $KASH_PARTNER_KEY" -H "Idempotency-Key: $(uuidgen)"

curl -X POST "$KASH_API/partner/accounts/$ACCOUNT_ID/reactivate" \
  -H "X-API-Key: $KASH_PARTNER_KEY" -H "Idempotency-Key: $(uuidgen)"

• Suspend moves an active account to suspended. Trades and withdrawals are refused until you reactivate it. The account keeps its funds, can still be read and released, and can still redeem winnings.
• Reactivate moves a suspended account back to active.
• Asking for the status the account already has answers 200 with _meta.idempotent: true and changes nothing.
• Any other status answers 409 ACCOUNT_NOT_ACTIVE, and the detail names the status. A provisioning or provisioning_failed account can be neither suspended nor reactivated.

​

Account resource

​

Next