--- title: "Create counterparty account" method: POST path: "/v1/counterparties/{counterpartyId}/accounts" tags: ["Counterparties"] --- # Create counterparty account `POST /v1/counterparties/{counterpartyId}/accounts` ## Request - Base URL: `http://localhost:8787` - URL: `http://localhost:8787/v1/counterparties/{counterpartyId}/accounts` - Auth: HTTP bearer Creates a payment account for a counterparty. For accountKind "crypto_wallet", details.network must be "solana" and details.address must be a Solana wallet address. ## Path parameters - `counterpartyId` string, required: Counterparty identifier. ## Headers - `x-project-id` string: Required for dashboard sessions. API keys use their assigned project. - `Idempotency-Key` string: Optional, and honored when sent. 1-255 printable ASCII characters; send a UUID per logical operation and reuse it on every retry. Within 24 hours, a retry with the same key and the same request returns the stored status and body with the response header `Idempotent-Replayed: true`. Keys are scoped to the credential: within 24 hours, the same key with a different request, or from a different credential, returns 422 `IDEMPOTENCY_KEY_REUSED`; after that, the same key from a different credential runs as a new request. A rotated API key is a new credential, so after any rotation read the resource with GET to see whether the original request ran, and never resend a money request under the new credential without checking first. A key whose original request is still running returns 409 `IDEMPOTENCY_KEY_IN_FLIGHT` with `Retry-After`. A 400, 401, 403, 409 or 429 refusal is not stored, so the same key runs again once the cause is fixed. Access is checked before the key on every request, so a refused request never claims the key, and a credential that has since lost access to the named resource gets 403 instead of the stored response. A replay is a snapshot of the original response: read the current state with GET instead of sending the request again. If the original request never recorded its outcome (it crashed), a same-key retry gets 409 `IDEMPOTENCY_KEY_IN_FLIGHT` until 15 minutes plus the route's lease have passed since the original was sent (about 16 minutes, or about 20 for transfer batches), then 409 `IDEMPOTENCY_KEY_OUTCOME_UNKNOWN` with no `Retry-After`, as does every later retry with that key: read the resource with GET to see whether it ran, then send again with a new key. A 5xx is stored and replayed like any other answer; retry it with a new key. ## Request body - object: Create counterparty account request body. - `accountKind` 'crypto_wallet', required: Counterparty account kind. - `label` string: Optional account label. - `details` object: For crypto_wallet accounts, must include network: "solana" and address as a Solana wallet address. - `providerAccountData` object: Provider-specific metadata to preserve with the account. ## Response `201` Counterparty account created - object: Standard success response envelope. - `data` object, required: Counterparty account response payload. - `account` object, required: Counterparty payment account record. - `id` string, required: Counterparty account identifier. - `organizationId` string, required: Organization identifier. - `projectId` string, required: Project identifier. - `counterpartyId` string, required: Counterparty identifier. - `accountKind` 'crypto_wallet', required: Counterparty account kind. - `label` string, nullable, required: Optional human-readable account label. - `details` object, required: Account details. For crypto_wallet accounts, include network: "solana" and address as a Solana wallet address. - `providerAccountData` object, required: Provider-specific account metadata preserved by SDP. - `status` 'active' | 'archived', required: Counterparty account status. - `createdAt` string, date-time, required: Creation timestamp. - `updatedAt` string, date-time, required: Last update timestamp. - `meta` object, required: Response metadata. - `requestId` string, required: Request identifier for tracing. - `timestamp` string, date-time, required: ISO 8601 timestamp. ## Other responses - `400`: Error - `401`: Error - `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. - `404`: Error - `409`: Error - `422`: Error - `500`: Error ## Changes - **2026-11-02** `9f0b1d561064`: 7 warning - added the new `CUSTODY_POLICY_REFUSED` enum value to the `error/code` response property for the response status `400` - added the new `CUSTODY_POLICY_REFUSED` enum value to the `error/code` response property for the response status `401` - added the new `CUSTODY_POLICY_REFUSED` enum value to the `error/code` response property for the response status `403` - added the new `CUSTODY_POLICY_REFUSED` enum value to the `error/code` response property for the response status `404` - …3 more - **2026-10-30** `f4a0135eca08`: 42 warning - added the new `RPC_UNAVAILABLE` enum value to the `error/code` response property for the response status `400` - added the new `RPC_UNAVAILABLE` enum value to the `error/code` response property for the response status `401` - added the new `RPC_UNAVAILABLE` enum value to the `error/code` response property for the response status `403` - added the new `RPC_UNAVAILABLE` enum value to the `error/code` response property for the response status `404` - …38 more - …earlier changes not shown [Operation history](https://skmtc.dev/solana/apis/solana-developer-platform-api/changes/v1/counterparties/:counterpartyId/accounts/post.md) --- [API](https://skmtc.dev/solana/apis/solana-developer-platform-api.md) - [All operations](https://skmtc.dev/solana/apis/solana-developer-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/solana/apis/solana-developer-platform-api/revisions/47682f5c382e?raw)