Update counterparty account

Updates a counterparty payment account.

PATCH/v1/counterparties/{counterpartyId}/accounts/{counterpartyAccountId}Run in dashboard

At least one field must be provided. Changing details to an address already on another of the counterparty's active accounts answers 409 CONFLICT.

Requires an API key with the counterparties.execute action.

Path parameters

  • counterpartyId · string · required · min length 1 · example cpty_example

    Counterparty identifier.

  • counterpartyAccountId · string · required · min length 1 · example cpacct_example

    Counterparty account identifier.

Headers

  • x-project-id · string · min length 1 · example prj_example

    Required for dashboard sessions. API keys use their assigned project.

  • Idempotency-Key · string

    Use a unique 1–255 printable ASCII key per operation. Reuse it with the same request on retries. An in-flight attempt returns 409; a changed request returns 422. Retry and recovery rules.

Request body

application/json · required

Update counterparty account request body. At least one field must be provided.

  • label · string | null · min length 1 · max length 256 · example Primary USDC wallet

    Updated account label. Use null to clear.

  • details · object

    Updated account details. Crypto-wallet accounts must retain network: "solana" and a valid Solana wallet address.

    • * · any

  • providerAccountData · object

    Updated provider-specific metadata.

    • * · any

Responses

  • 200 Counterparty account updated

    • data · object · required

      Counterparty account response payload.

      • account · object · required

        Counterparty payment account record.

        • id · string · required · example cpacct_example

          Counterparty account identifier.

        • organizationId · string · required · min length 1 · example org_example

          Organization identifier.

        • projectId · string · required · min length 1 · example prj_example

          Project identifier.

        • counterpartyId · string · required · min length 1 · example cpty_example

          Counterparty identifier.

        • accountKind · string · required · always crypto_wallet · example crypto_wallet

          Counterparty account kind.

        • label · string | null · required · example USDC wallet

          Optional human-readable account label.

        • details · object · required

          Account details. For crypto_wallet accounts, include network: "solana" and address as a Solana wallet address.

          • * · any

        • providerAccountData · object · required

          Provider-specific account metadata preserved by SDP.

          • * · any

        • status · string · required · one of active, archived · example active

          Counterparty account status.

        • createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

          Creation timestamp.

        • updatedAt · string · required · format date-time · example 2025-01-02T00:00:00.000Z

          Last update timestamp.

    • meta · object · required

      Response metadata.

      • requestId · string · required · min length 1 · example req_example

        Request identifier for tracing.

      • timestamp · string · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

  • 400 Bad Request

    • error · object · required

      Standard error payload.

      • code · string · required

        Machine-readable error code.

      • message · string · required

        Human-readable error message.

      • details · object

        Optional error details for debugging.

        • * · any

    • meta · object

      • requestId · string · min length 1 · example req_example

        Request identifier for tracing.

  • 401 Unauthorized

    Same fields as 400.

  • 403 Forbidden. Requires the counterparties.execute action: an API key must hold it (a module's manage or execute also covers its read), and a signed-in member's organization role must include it. Without it the error is INSUFFICIENT_PERMISSIONS and error.details.action names the action. Any other 403 names its own reason.

    Same fields as 400.

  • 404 Not Found

    Same fields as 400.

  • 409 Conflict

    Same fields as 400.

  • 422 Unprocessable Entity

    Same fields as 400.

  • 500 Internal Server Error

    Same fields as 400.

Example request

IDEMPOTENCY_KEY=$(uuidgen)
curl -X PATCH 'https://api-beta.solana.com/v1/counterparties/cpty_example/accounts/cpacct_example' \
  -H "Authorization: Bearer $SDP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Primary USDC wallet",
    "details": {
      "network": "solana",
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
    },
    "providerAccountData": {}
  }'
// Reuse this key when you retry this request.
const idempotencyKey = crypto.randomUUID();
const res = await fetch("https://api-beta.solana.com/v1/counterparties/cpty_example/accounts/cpacct_example", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.SDP_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "label": "Primary USDC wallet",
    "details": {
      "network": "solana",
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
    },
    "providerAccountData": {}
  })
});
import os, requests, uuid

# Reuse this key when you retry this request.
idempotency_key = str(uuid.uuid4())
r = requests.patch("https://api-beta.solana.com/v1/counterparties/cpty_example/accounts/cpacct_example",
  headers={"Authorization": f"Bearer {os.environ['SDP_API_KEY']}", "Idempotency-Key": idempotency_key},
  json={
    "label": "Primary USDC wallet",
    "details": {
      "network": "solana",
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
    },
    "providerAccountData": {}
  })

Example responses

JSON
{
  "data": {
    "account": {
      "id": "cpacct_example",
      "organizationId": "org_example",
      "projectId": "prj_example",
      "counterpartyId": "cpty_example",
      "accountKind": "crypto_wallet",
      "label": "USDC wallet",
      "details": {
        "network": "solana",
        "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
      },
      "providerAccountData": {},
      "status": "active",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-02T00:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}
JSON
{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Missing action: counterparties.execute",
    "details": {
      "action": "counterparties.execute"
    }
  },
  "meta": {
    "requestId": "req_example"
  }
}

Error responses use the standard error shape.