# Create a payment instrument
<a name="payments-create-instrument"></a>

A payment instrument represents an embedded crypto wallet that an agent uses to pay merchants on behalf of a user. Each instrument is associated with a specific blockchain network. For the complete request and response schema, see [CreatePaymentInstrument](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreatePaymentInstrument.html) in the API Reference.

**Example**  

```
aws bedrock-agentcore create-payment-instrument \
    --payment-manager-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --payment-connector-id "my-connector-id" \
    --user-id "test-user-123" \
    --payment-instrument-type "EMBEDDED_CRYPTO_WALLET" \
    --payment-instrument-details '{
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "myemail@example.com"}}]
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2
```
For Solana compatible chain, use `"network": "SOLANA"`.

```
import boto3
import uuid

dp_client = boto3.client("bedrock-agentcore", region_name="us-west-2",
    endpoint_url="https://bedrock-agentcore.us-west-2.amazonaws.com")

# Create payment instrument (Ethereum)
instrument = dp_client.create_payment_instrument(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentConnectorId=PAYMENT_CONNECTOR_ID,
    paymentInstrumentType="EMBEDDED_CRYPTO_WALLET",
    paymentInstrumentDetails={
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{
                "email": {
                    "emailAddress": "myemail@example.com"
                }
            }]
        },
    },
    clientToken=str(uuid.uuid4()),
)
```
For Solana compatible chain, use enum `SOLANA` for network input.

```
from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=mgr["paymentManagerArn"],
    region_name="us-west-2"
)

# Create payment instrument (Ethereum)
instrument = manager.create_payment_instrument(
    user_id="test-user-123",
    payment_connector_id=PAYMENT_CONNECTOR_ID,
    payment_instrument_type="EMBEDDED_CRYPTO_WALLET",
    payment_instrument_details={"embeddedCryptoWallet": {"network": "ETHEREUM",
    "linkedAccounts": [{
                "email": {
                    "emailAddress": "myemail@example.com"
                }
            }]
   }},
)
```
For Solana compatible chain, use enum `SOLANA` for network input.

**Note**  
Once the payment instrument is created, the end user must fund the instrument and grant signing permissions before the agent can process payments. To learn more about funding your wallet, see [How AgentCore payments works](payments-how-it-works.md#payments-how-it-works-funding-wallet).

## Get a payment instrument
<a name="payments-create-instrument-get"></a>

**Example**  

```
aws bedrock-agentcore get-payment-instrument \
    --payment-manager-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --payment-instrument-id "payment-instrument-abc123" \
    --user-id "test-user-123" \
    --region us-west-2
```

```
response = dp_client.get_payment_instrument(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentInstrumentId="payment-instrument-abc123"
)
print(f"Status: {response['status']}, Network: {response['paymentInstrumentDetails']['embeddedCryptoWallet']['network']}")
```

```
instrument = manager.get_payment_instrument(
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-abc123"
)
print(f"Status: {instrument['status']}")
```

## List payment instruments
<a name="payments-create-instrument-list"></a>

**Example**  

```
aws bedrock-agentcore list-payment-instruments \
    --payment-manager-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --user-id "test-user-123" \
    --region us-west-2
```

```
response = dp_client.list_payment_instruments(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    userId="test-user-123"
)
for inst in response['paymentInstruments']:
    print(f"{inst['paymentInstrumentId']} - {inst['status']}")
```

```
instruments = manager.list_payment_instruments(
    user_id="test-user-123"
)
for inst in instruments['paymentInstruments']:
    print(f"{inst['paymentInstrumentId']} - {inst['status']}")
```

## Check instrument balance
<a name="payments-create-instrument-balance"></a>

**Example**  

```
aws bedrock-agentcore get-payment-instrument-balance \
    --payment-manager-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --payment-instrument-id "payment-instrument-abc123" \
    --region us-west-2
```

```
response = dp_client.get_payment_instrument_balance(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentInstrumentId="payment-instrument-abc123"
)
print(f"Balance: {response['amount']} {response['currency']}")
```

```
balance = manager.get_payment_instrument_balance(
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-abc123"
)
print(f"Balance: {balance['amount']} {balance['currency']}")
```

## Delete a payment instrument
<a name="payments-create-instrument-delete"></a>

**Example**  

```
aws bedrock-agentcore delete-payment-instrument \
    --payment-manager-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --payment-instrument-id "payment-instrument-abc123" \
    --region us-west-2
```

```
dp_client.delete_payment_instrument(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentInstrumentId="payment-instrument-abc123"
)
```

```
manager.delete_payment_instrument(
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-abc123"
)
```